> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.
# Técnicas prácticas de Laravel Telescope
> Presentamos patrones prácticos para aprovechar Telescope al máximo en desarrollo local. Se resumen conocimientos que no aparecen solo en la documentación oficial: detección de N+1, seguimiento con etiquetas, watchers personalizados, uso del Dump watcher, etc.
Para la instalación y configuración básicas, consulta la [página de la guía](/es/telescope). 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](/es/pulse) o [Laravel Nightwatch](/es/blog/nightwatch-introduction).
***
## 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.
```mermaid theme={null}
sequenceDiagram
participant Navegador
participant Laravel
participant Telescope
participant DB
Navegador->>Laravel: GET /posts
Laravel->>DB: SELECT * FROM posts (1 query)
loop Por cada post
Laravel->>DB: SELECT * FROM users WHERE id = ? (N queries)
end
Laravel-->>Navegador: Respuesta
Laravel-->>Telescope: Registra el histórico de queries
Note over Telescope: La misma SELECT se repite N veces
se etiqueta como slow
```
Abre `/telescope` y en la pestaña Requests identifica las peticiones con mayor tiempo de ejecución.
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.
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.
```php theme={null}
// 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.
```php theme={null}
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.
```php theme={null}
// 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.
```php theme={null}
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`.
```php theme={null}
// 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](https://mailpit.axllent.org/), el flujo de desarrollo de emails mejora enormemente.
```ini theme={null}
# .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()`
```php theme={null}
// 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.
```php theme={null}
// 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.
```php theme={null}
$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 |
Para los detalles de instalación y configuración de los watchers, consulta la página de la guía.
Para la monitorización en producción, usa Nightwatch.
## Related topics
- [Introducción a Laravel Nightwatch](/es/blog/nightwatch-introduction.md)
- [Laravel Telescope](/es/telescope.md)
- [Búsqueda](/es/search.md)
- [Contracts (contratos)](/es/contracts.md)
- [Actualización de Laravel — Mayo de 2026](/es/blog/changelog/202605.md)