Técnicas prácticas de Laravel Telescope

Para la instalación y configuración básicas, consulta la página de la guía. En esta página presentamos patrones de uso prácticos en desarrollo local que no aparecen en la documentación oficial. Telescope es una herramienta exclusivamente para desarrollo local. Para monitorización en producción, usa Laravel Pulse o Laravel Nightwatch.

Detectar sistemáticamente el problema N+1

Se explica el flujo práctico de depuración de N+1 con Telescope. No basta con darse cuenta de que “se repite el mismo SELECT”; se puede realizar como flujo completo, incluida la verificación después de corregir.

Localiza peticiones lentas en Requests

Abre /telescope y en la pestaña Requests identifica las peticiones con mayor tiempo de ejecución.

Revisa el SQL ejecutado en Queries

Al abrir el detalle de la petición, se muestran todas las consultas SQL ejecutadas durante esa petición. Si se repiten sentencias SELECT similares, es un N+1.

Corrige añadiendo Eager Loading

Añade with() al código y revisa las queries de nuevo. Si el número de queries se ha reducido notablemente, la corrección está completa.

// Código que produce N+1
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->user->name; // Una query adicional por cada post
}

// Solución con Eager Loading
$posts = Post::with('user')->get();

Sin añadir al código dd() ni logs de depuración, se puede completar todo este flujo en el navegador.

Seguimiento de peticiones específicas con etiquetas

Telescope tiene una función de etiquetas. Con Telescope::tag() puedes añadir etiquetas arbitrarias a las entradas, y con el filtro del dashboard puedes acotar rápidamente solo las entradas con esa etiqueta. Es muy útil cuando quieres seguir solo el procesamiento relacionado con un ID de usuario o de pedido concreto.

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

// Sobreescribe el método tags del TelescopeServiceProvider
Telescope::tag(function (IncomingEntry $entry) {
    if ($entry->type === 'request') {
        return array_filter([
            'status:' . $entry->content['response_status'],
            auth()->check() ? 'user:' . auth()->id() : null,
        ]);
    }

    return [];
});

Con esto, basta con escribir user:42 en el Search de /telescope/requests para listar solo las peticiones del usuario ID=42.

Asignar etiquetas automáticamente a los modelos

Con el método tags del TelescopeServiceProvider puedes asignar un ID de modelo concreto a todas las entradas.

// TelescopeServiceProvider
Telescope::tag(function (IncomingEntry $entry) {
    return $entry->tags();
});

Además, implementando el contract HasTags en el modelo, cuando ese modelo se registra se le añaden etiquetas automáticamente.

use Laravel\Telescope\Contracts\EntriesRepository;

class Order extends Model implements \Laravel\Telescope\Contracts\HasTags
{
    public function telescopeTags(): array
    {
        return ['order:' . $this->id];
    }
}

Uso del Dump watcher

Al usar dump(), la salida se mezcla con la respuesta HTML y puede dificultar la depuración de APIs. Con el Dump watcher de Telescope puedes separar la salida de dump() de la respuesta del navegador y registrarla en el dashboard. El uso es sencillo. Basta con llamar a dump() teniendo abierta la pestaña “Dump” de /telescope.

// Controlador
public function index()
{
    $users = User::with('posts')->get();
    dump($users->first()->toArray()); // Se muestra en la pestaña dump de Telescope
    return response()->json($users);
}

Como solo se captura mientras la página está abierta, puedes monitorizar solo cuando lo necesites. A diferencia de dd(), no detiene la ejecución de la app, por lo que es útil para depurar mientras dejas correr peticiones consecutivas.

Facilitar la depuración de emails con la integración con Mailpit

Combinando el Mail watcher con el servidor SMTP local Mailpit, el flujo de desarrollo de emails mejora enormemente.

# .env
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025

En la pestaña Mail de Telescope puedes previsualizar los emails enviados tanto en HTML como en texto. En Mailpit puedes revisar los emails recibidos en el navegador, y también los archivos adjuntos y las puntuaciones de spam.

Para no enviar emails al exterior por error durante los tests, usa siempre en local un SMTP local como Mailpit o Mailhog.

Depuración de eventos y listeners

Las implementaciones event-driven suelen ser difíciles de depurar. Perseguir “¿se ha disparado el evento?” o “¿qué listener se ha llamado?” mirando los logs resulta pesado. Con el Events watcher de Telescope puedes consultar en una lista los eventos emitidos y sus listeners. Si un listener no se llama, revisa la entrada del evento en la pestaña Events.

El evento se emite pero no se muestran listeners → el listener no está registrado (revisa el EventServiceProvider)
El evento en sí no se emite → revisa la llamada a event()

// Flujo para comprobar en local en lugar de ejecutar un test
event(new OrderShipped($order));
// → Comprueba en /telescope/events si aparece OrderShipped
// → Comprueba si se ha llamado al listener SendShippingConfirmation

Depuración de jobs de cola

Depurar procesamiento asíncrono solo con logs es difícil. El Jobs watcher de Telescope registra desde el dispatch del job hasta el resultado de la ejecución. Al hacer clic en la entrada de un job fallido, puedes ver la traza y el mensaje de excepción. Al margen de la tabla queue:failed, también puedes verlo en Telescope, con lo que la investigación de la causa del fallo se agiliza.

// Al depurar jobs, es más fácil seguirlos con el driver sync
// .env
QUEUE_CONNECTION=sync

Con el driver sync, los jobs se ejecutan sincrónicamente dentro de la petición, y en el Requests watcher se incluye también el resultado de la ejecución del job.

Depuración del cliente HTTP

Al depurar comunicaciones con APIs externas, el HTTP Client Watcher resulta útil. Se registran las peticiones realizadas con la facade Http:: y sus respuestas.

$response = Http::get('https://api.example.com/users');
// → Se puede consultar en /telescope/client-requests

Se ven de un vistazo el contenido de la respuesta, el código de estado y el tiempo de ejecución. Sin necesidad de escribir dd($response->json()), puedes revisarlo en el dashboard.

Conclusión

Técnica	Efecto
Flujo N+1	Descubrir y corregir problemas de consultas sistemáticamente sin dd()
Etiquetado	Filtrado rápido de registros de un usuario o modelo concreto
Dump watcher	Ver salidas de dump sin ensuciar la respuesta de la API
Integración con Mailpit	Desarrollo de email local más cómodo
Events watcher	Confirmación visual del disparo de eventos/listeners
Jobs + sync	Depurar procesamiento asíncrono ejecutándolo de forma sincrónica
Cliente HTTP	Registro y comprobación de comunicaciones con APIs externas

Guía de Laravel Telescope

Para los detalles de instalación y configuración de los watchers, consulta la página de la guía.

Laravel Nightwatch

Para la monitorización en producción, usa Nightwatch.

​Detectar sistemáticamente el problema N+1

​Seguimiento de peticiones específicas con etiquetas

​Asignar etiquetas automáticamente a los modelos

​Uso del Dump watcher

​Facilitar la depuración de emails con la integración con Mailpit

​Depuración de eventos y listeners

​Depuración de jobs de cola

​Depuración del cliente HTTP

​Conclusión

Guía de Laravel Telescope

Laravel Nightwatch

Detectar sistemáticamente el problema N+1

Seguimiento de peticiones específicas con etiquetas

Asignar etiquetas automáticamente a los modelos

Uso del Dump watcher

Facilitar la depuración de emails con la integración con Mailpit

Depuración de eventos y listeners

Depuración de jobs de cola

Depuración del cliente HTTP

Conclusión