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

> Introduzione a Laravel Telescope. Copriamo l'installazione dedicata all'ambiente locale e la configurazione dei watcher.

## Cos'è Laravel Telescope

[Laravel Telescope](https://github.com/laravel/telescope) è uno strumento di debug ufficiale che rende visibile lo stato interno di un'applicazione Laravel.
Registra in dettaglio richieste, eccezioni, query, job, log, email, notifiche, operazioni di cache, esecuzioni pianificate e altro.

È uno strumento di debug **esclusivo per l'ambiente di sviluppo locale**. Per il monitoraggio in produzione usa [Laravel Pulse](/it/pulse) o [Laravel Nightwatch](/it/blog/nightwatch-introduction).

### Livelli monitorati

```mermaid theme={null}
flowchart LR
    A["Livello HTTP<br>Request / Response"] --> T["Salvataggio degli entry di Telescope"]
    B["Livello applicativo<br>Events / Logs / Exceptions"] --> T
    C["Livello dati<br>DB Queries / Redis / Cache"] --> T
    D["Livello asincrono<br>Queue Jobs / Schedule / Notifications"] --> T
    T --> E["Dashboard<br>/telescope"]
```

***

## Installazione

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

  <Step title="Pubblica gli asset e le migration">
    ```shell theme={null}
    php artisan telescope:install
    ```
  </Step>

  <Step title="Esegui le migration">
    ```shell theme={null}
    php artisan migrate
    ```
  </Step>
</Steps>

Dopo l'installazione, puoi accedere alla dashboard su `/telescope`.

## Installazione dedicata all'ambiente locale (consigliata)

<Info>
  Se il tuo obiettivo principale è il debug in sviluppo locale, si consiglia una configurazione con installazione tramite `--dev` e registrazione manuale del service provider limitata al solo ambiente `local`.
</Info>

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

php artisan telescope:install
php artisan migrate
```

Dopo aver eseguito `telescope:install`, rimuovi la registrazione di `TelescopeServiceProvider` da `bootstrap/providers.php`.
Poi registralo manualmente nel metodo `register` di `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);
    }
}
```

Inoltre, disattiva l'auto-discovery in `composer.json`.

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

***

## Watcher disponibili

I watcher raccolgono telemetria durante l'esecuzione delle richieste e dei comandi.
Gestisci abilitazione e configurazione in `config/telescope.php`.

<AccordionGroup>
  <Accordion title="Request Watcher">
    Registra richieste, header, sessione e risposte.\
    Puoi limitare la dimensione della risposta registrata con `size_limit`.
  </Accordion>

  <Accordion title="Query Watcher (particolarmente importante)">
    Registra SQL, binding e tempo di esecuzione.\
    Di default, le query che superano i **100ms** vengono registrate con il tag `slow`, rendendolo molto utile per individuare i colli di bottiglia prestazionali.

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

  <Accordion title="Job Watcher">
    Registra l'invio e il risultato dell'esecuzione dei job in coda.
  </Accordion>

  <Accordion title="Exception Watcher">
    Registra le eccezioni segnalate a `report` e lo stack trace.
  </Accordion>

  <Accordion title="Log Watcher">
    Registra i log dell'applicazione.\
    Di default vengono registrati i log di livello `error` o superiore; puoi abbassare la soglia fino a `debug` tramite configurazione.
  </Accordion>

  <Accordion title="Command Watcher">
    Registra argomenti, opzioni, output e codice di uscita dei comandi Artisan.
  </Accordion>

  <Accordion title="Event Watcher">
    Registra il payload degli eventi emessi e le informazioni sui listener (gli eventi interni di Laravel sono esclusi).
  </Accordion>

  <Accordion title="Cache Watcher">
    Registra hit, miss, aggiornamenti ed eliminazioni della cache.
  </Accordion>

  <Accordion title="Redis Watcher">
    Registra i comandi Redis eseguiti dall'applicazione.
  </Accordion>

  <Accordion title="Model Watcher">
    Registra gli eventi dei modelli Eloquent e, se necessario, raccoglie anche il conteggio delle hydration.
  </Accordion>

  <Accordion title="Notification Watcher">
    Registra le notifiche inviate.
  </Accordion>

  <Accordion title="Mail Watcher">
    Consente l'anteprima delle email inviate nel browser e il download come `.eml`.
  </Accordion>

  <Accordion title="HTTP Client Watcher">
    Registra le richieste HTTP client in uscita.
  </Accordion>

  <Accordion title="Gate Watcher">
    Registra il risultato dei controlli di autorizzazione di Gate / Policy.
  </Accordion>

  <Accordion title="Schedule Watcher">
    Registra i comandi eseguiti dallo scheduler e il loro output.
  </Accordion>

  <Accordion title="View Watcher">
    Registra nome, path, dati e composer delle viste renderizzate.
  </Accordion>

  <Accordion title="Batch Watcher">
    Registra le informazioni dei batch di code (job e informazioni sulla connessione).
  </Accordion>

  <Accordion title="Dump Watcher">
    Registra le uscite di `dump` mentre la tab Dump di Telescope è aperta.
  </Accordion>
</AccordionGroup>

***

## Riepilogo

| Attività                         | Configurazione consigliata                                           |
| -------------------------------- | -------------------------------------------------------------------- |
| Installazione                    | `composer require laravel/telescope --dev`                           |
| Isolamento sicuro al solo locale | Registrazione manuale del provider + `dont-discover`                 |
| Analisi delle prestazioni del DB | Sfrutta il tag delle slow query del Query Watcher (100ms di default) |

## Prossimi passi

<Columns cols={2}>
  <Card title="Laravel Pulse" icon="chart-line" href="/it/pulse">
    Introduci la dashboard di aggregazione delle prestazioni per l'ambiente di produzione.
  </Card>

  <Card title="Laravel Nightwatch" icon="moon" href="/it/blog/nightwatch-introduction">
    Per il monitoraggio in tempo reale in produzione usa Nightwatch.
  </Card>
</Columns>


## Related topics

- [Tecniche pratiche di Laravel Telescope](/it/blog/telescope-introduction.md)
- [Laravel Pulse](/it/pulse.md)
- [Creare un server MCP con Laravel](/it/advanced/mcp-server.md)
- [Gestire la compatibilità tra versioni dei pacchetti](/it/advanced/package-versioning.md)
- [Introduzione a Laravel Nightwatch](/it/blog/nightwatch-introduction.md)