> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Telescope

> Explicamos la instalación de Laravel Telescope. Cubrimos la instalación exclusiva para local y la configuración de los watchers.

## ¿Qué es Laravel Telescope?

[Laravel Telescope](https://github.com/laravel/telescope) es la herramienta oficial de depuración que permite visualizar el estado interno de una aplicación Laravel.
Puede registrar en detalle solicitudes, excepciones, consultas, jobs, logs, correos, notificaciones, operaciones de caché, ejecuciones programadas y más.

Es una herramienta de depuración **exclusiva para el entorno de desarrollo local**. Para monitoreo en producción, usa [Laravel Pulse](/es/pulse) o [Laravel Nightwatch](/es/blog/nightwatch-introduction).

### Capas monitorizadas

```mermaid theme={null}
flowchart LR
    A["Capa HTTP<br>Request / Response"] --> T["Guardado de entradas de Telescope"]
    B["Capa de aplicación<br>Events / Logs / Exceptions"] --> T
    C["Capa de datos<br>DB Queries / Redis / Cache"] --> T
    D["Capa asíncrona<br>Queue Jobs / Schedule / Notifications"] --> T
    T --> E["Dashboard<br>/telescope"]
```

***

## Instalación

<Steps>
  <Step title="Instalar Telescope">
    ```shell theme={null}
    composer require laravel/telescope
    ```
  </Step>

  <Step title="Publicar assets y migraciones">
    ```shell theme={null}
    php artisan telescope:install
    ```
  </Step>

  <Step title="Ejecutar las migraciones">
    ```shell theme={null}
    php artisan migrate
    ```
  </Step>
</Steps>

Tras la instalación, puedes acceder al dashboard en `/telescope`.

## Instalación solo para entorno local (recomendado)

<Info>
  Si el objetivo principal es depurar en desarrollo local, se recomienda instalarlo con `--dev` y registrar el service provider manualmente solo en el entorno `local`.
</Info>

```shell theme={null}
composer require laravel/telescope --dev

php artisan telescope:install
php artisan migrate
```

Tras ejecutar `telescope:install`, elimina el registro de `TelescopeServiceProvider` en `bootstrap/providers.php`.
Después, regístralo manualmente en el método `register` de `App\Providers\AppServiceProvider`.

```php theme={null}
public function register(): void
{
    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}
```

Además, desactiva el auto-discovery en `composer.json`.

```json theme={null}
{
  "extra": {
    "laravel": {
      "dont-discover": [
        "laravel/telescope"
      ]
    }
  }
}
```

***

## Watchers disponibles

Los watchers recogen telemetría al procesar solicitudes o al ejecutar comandos.
Se activan y configuran en `config/telescope.php`.

<AccordionGroup>
  <Accordion title="Request Watcher">
    Registra la solicitud, cabeceras, sesión y respuesta.\
    Con `size_limit` puedes limitar el tamaño registrado de la respuesta.
  </Accordion>

  <Accordion title="Query Watcher (especialmente importante)">
    Registra el SQL, bindings y tiempo de ejecución.\
    Por defecto, las consultas de más de **100 ms** se etiquetan con `slow`, lo que es muy útil para detectar cuellos de botella de rendimiento.

    ```php theme={null}
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ```
  </Accordion>

  <Accordion title="Job Watcher">
    Registra la puesta en cola de jobs y el resultado de su ejecución.
  </Accordion>

  <Accordion title="Exception Watcher">
    Registra las excepciones reportables y sus trazas.
  </Accordion>

  <Accordion title="Log Watcher">
    Registra los logs de la aplicación.\
    Por defecto captura a partir de `error`, y puedes bajarlo hasta `debug` con la configuración.
  </Accordion>

  <Accordion title="Command Watcher">
    Registra los argumentos, opciones, salida y código de salida de los comandos Artisan.
  </Accordion>

  <Accordion title="Event Watcher">
    Registra el payload y los listeners de los eventos despachados (se excluyen los eventos internos de Laravel).
  </Accordion>

  <Accordion title="Cache Watcher">
    Registra hits, misses, actualizaciones y eliminaciones de caché.
  </Accordion>

  <Accordion title="Redis Watcher">
    Registra los comandos de Redis ejecutados desde la aplicación.
  </Accordion>

  <Accordion title="Model Watcher">
    Registra eventos de modelos Eloquent y, si se desea, también el número de hidrataciones.
  </Accordion>

  <Accordion title="Notification Watcher">
    Registra las notificaciones enviadas.
  </Accordion>

  <Accordion title="Mail Watcher">
    Permite previsualizar en el navegador los correos enviados y descargarlos como `.eml`.
  </Accordion>

  <Accordion title="HTTP Client Watcher">
    Registra las solicitudes salientes del cliente HTTP.
  </Accordion>

  <Accordion title="Gate Watcher">
    Registra el resultado de las verificaciones de autorización con Gate / Policy.
  </Accordion>

  <Accordion title="Schedule Watcher">
    Registra los comandos ejecutados por el scheduler y su salida.
  </Accordion>

  <Accordion title="View Watcher">
    Registra el nombre, la ruta, los datos y los composers de las vistas renderizadas.
  </Accordion>

  <Accordion title="Batch Watcher">
    Registra la información de los batches de cola (jobs y datos de conexión).
  </Accordion>

  <Accordion title="Dump Watcher">
    Registra la salida de `dump` mientras la pestaña Dump de Telescope está abierta.
  </Accordion>
</AccordionGroup>

***

## Resumen

| Tarea                            | Configuración recomendada                                                       |
| -------------------------------- | ------------------------------------------------------------------------------- |
| Instalación                      | `composer require laravel/telescope --dev`                                      |
| Aislamiento fiable solo en local | Registro manual del provider + `dont-discover`                                  |
| Análisis de rendimiento de la BD | Aprovechar la etiqueta de consulta lenta del Query Watcher (100 ms por defecto) |

## Próximos pasos

<Columns cols={2}>
  <Card title="Laravel Pulse" icon="chart-line" href="/es/pulse">
    Adopta el dashboard de agregación de rendimiento para producción.
  </Card>

  <Card title="Laravel Nightwatch" icon="moon" href="/es/blog/nightwatch-introduction">
    Usa Nightwatch para el monitoreo en tiempo real en producción.
  </Card>
</Columns>


## Related topics

- [Técnicas prácticas de Laravel Telescope](/es/blog/telescope-introduction.md)
- [Laravel Pulse](/es/pulse.md)
- [Crear un servidor MCP con Laravel](/es/advanced/mcp-server.md)
- [Gestión de la compatibilidad de versiones de paquetes](/es/advanced/package-versioning.md)
- [Introducción a Laravel Nightwatch](/es/blog/nightwatch-introduction.md)