> ## 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

> Introduction à Laravel Telescope. Installation en mode local uniquement et configuration des watchers.

## Qu'est-ce que Laravel Telescope

[Laravel Telescope](https://github.com/laravel/telescope) est l'outil de débogage officiel qui donne une visibilité sur l'état interne d'une application Laravel.
Il enregistre en détail les requêtes, exceptions, requêtes SQL, jobs, logs, e-mails, notifications, opérations de cache, exécutions planifiées, etc.

Il s'agit d'un outil de débogage **exclusivement destiné à l'environnement de développement local**. Pour la supervision en production, utilisez [Laravel Pulse](/fr/pulse) ou [Laravel Nightwatch](/fr/blog/nightwatch-introduction).

### Couches surveillées

```mermaid theme={null}
flowchart LR
    A["Couche HTTP<br>Request / Response"] --> T["Enregistrement des entrées Telescope"]
    B["Couche application<br>Events / Logs / Exceptions"] --> T
    C["Couche données<br>Requêtes DB / Redis / Cache"] --> T
    D["Couche asynchrone<br>Queue Jobs / Schedule / Notifications"] --> T
    T --> E["Tableau de bord<br>/telescope"]
```

***

## Installation

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

  <Step title="Publier les assets et migrations">
    ```shell theme={null}
    php artisan telescope:install
    ```
  </Step>

  <Step title="Exécuter les migrations">
    ```shell theme={null}
    php artisan migrate
    ```
  </Step>
</Steps>

Une fois installé, accédez au tableau de bord à `/telescope`.

## Installation en mode local uniquement (recommandé)

<Info>
  Si votre objectif principal est le débogage en local, il est recommandé d'installer avec `--dev` et d'enregistrer manuellement le service provider uniquement en environnement `local`.
</Info>

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

php artisan telescope:install
php artisan migrate
```

Après avoir lancé `telescope:install`, retirez l'enregistrement de `TelescopeServiceProvider` de `bootstrap/providers.php`.
Puis enregistrez-le manuellement dans la méthode `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);
    }
}
```

Désactivez également l'auto-discovery dans `composer.json`.

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

***

## Watchers disponibles

Les watchers collectent la télémétrie lors des requêtes et de l'exécution des commandes.
Gérez l'activation et la configuration dans `config/telescope.php`.

<AccordionGroup>
  <Accordion title="Request Watcher">
    Enregistre les requêtes, en-têtes, sessions et réponses.\
    `size_limit` permet de limiter la taille des réponses enregistrées.
  </Accordion>

  <Accordion title="Query Watcher (particulièrement important)">
    Enregistre le SQL, les bindings et le temps d'exécution.\
    Par défaut, les requêtes de plus de **100 ms** sont taguées `slow`, ce qui est très efficace pour détecter les goulets d'étranglement.

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

  <Accordion title="Job Watcher">
    Enregistre la mise en file des jobs et leur résultat d'exécution.
  </Accordion>

  <Accordion title="Exception Watcher">
    Enregistre les exceptions destinées à `report` et leurs traces.
  </Accordion>

  <Accordion title="Log Watcher">
    Enregistre les logs de l'application.\
    Par défaut à partir du niveau `error`, mais on peut abaisser jusqu'à `debug` via la configuration.
  </Accordion>

  <Accordion title="Command Watcher">
    Enregistre les arguments, options, sortie et code de sortie des commandes Artisan.
  </Accordion>

  <Accordion title="Event Watcher">
    Enregistre les payloads et listeners des événements dispatchés (à l'exception des événements internes de Laravel).
  </Accordion>

  <Accordion title="Cache Watcher">
    Enregistre les hits, misses, mises à jour et suppressions du cache.
  </Accordion>

  <Accordion title="Redis Watcher">
    Enregistre les commandes Redis exécutées depuis l'application.
  </Accordion>

  <Accordion title="Model Watcher">
    Enregistre les événements de modèles Eloquent et, au besoin, le nombre d'hydratations.
  </Accordion>

  <Accordion title="Notification Watcher">
    Enregistre les notifications envoyées.
  </Accordion>

  <Accordion title="Mail Watcher">
    Prévisualise les e-mails envoyés dans le navigateur et permet de les télécharger au format `.eml`.
  </Accordion>

  <Accordion title="HTTP Client Watcher">
    Enregistre les requêtes HTTP sortantes du client.
  </Accordion>

  <Accordion title="Gate Watcher">
    Enregistre le résultat des vérifications d'autorisation Gate / Policy.
  </Accordion>

  <Accordion title="Schedule Watcher">
    Enregistre les commandes exécutées par le scheduler et leur sortie.
  </Accordion>

  <Accordion title="View Watcher">
    Enregistre le nom, le chemin, les données et les composers des vues rendues.
  </Accordion>

  <Accordion title="Batch Watcher">
    Enregistre les informations des batchs de queue (jobs, informations de connexion).
  </Accordion>

  <Accordion title="Dump Watcher">
    Enregistre la sortie des `dump` tant que l'onglet Dump de Telescope est ouvert.
  </Accordion>
</AccordionGroup>

***

## Récapitulatif

| Tâche                      | Configuration recommandée                                      |
| -------------------------- | -------------------------------------------------------------- |
| Installation               | `composer require laravel/telescope --dev`                     |
| Isolation locale fiable    | Enregistrement manuel du provider + `dont-discover`            |
| Analyse de performances DB | Exploiter le tag « slow » du Query Watcher (100 ms par défaut) |

## Prochaines étapes

<Columns cols={2}>
  <Card title="Laravel Pulse" icon="chart-line" href="/fr/pulse">
    Mettez en place un tableau de bord d'agrégation de performance pour la production.
  </Card>

  <Card title="Laravel Nightwatch" icon="moon" href="/fr/blog/nightwatch-introduction">
    Utilisez Nightwatch pour la supervision en temps réel de la production.
  </Card>
</Columns>


## Related topics

- [Techniques pratiques de Laravel Telescope](/fr/blog/telescope-introduction.md)
- [Laravel Pulse](/fr/pulse.md)
- [Créer un serveur MCP avec Laravel](/fr/advanced/mcp-server.md)
- [Gestion de la compatibilité de versions de package](/fr/advanced/package-versioning.md)
- [Introduction à Laravel Nightwatch](/fr/blog/nightwatch-introduction.md)