> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.
# Tecniche pratiche di Laravel Telescope
> Presenta pattern pratici per sfruttare al massimo Telescope in sviluppo locale. Rileva N+1, tracciamento con tag, watcher personalizzati, uso del Dump watcher: raccoglie know-how che non emerge dalla sola documentazione ufficiale.
Per l'installazione e la configurazione di base fai riferimento alla [pagina della guida](/it/telescope). In questa pagina presentiamo pattern pratici, non presenti nella documentazione ufficiale, per lo sviluppo in locale.
Telescope è uno strumento **esclusivo per lo sviluppo locale**. Per il monitoraggio della produzione usa [Laravel Pulse](/it/pulse) o [Laravel Nightwatch](/it/blog/nightwatch-introduction).
***
## Scoprire il problema N+1 in modo sistematico
Ecco un flusso pratico di debug N+1 con Telescope. Non ci si limita ad accorgersi che "la stessa SELECT si ripete", ma si effettua un intero workflow che include anche la verifica dopo la correzione.
```mermaid theme={null}
sequenceDiagram
participant Browser
participant Laravel
participant Telescope
participant DB
Browser->>Laravel: GET /posts
Laravel->>DB: SELECT * FROM posts (1 query)
loop Per ogni post
Laravel->>DB: SELECT * FROM users WHERE id = ? (N query)
end
Laravel-->>Browser: Risposta
Laravel-->>Telescope: Registra la cronologia query
Note over Telescope: Stessa SELECT N volte
viene aggiunto il tag slow
```
Apri `/telescope` e individua nel tab Requests le richieste con tempo di esecuzione elevato.
Aprendo il dettaglio della richiesta vedi tutte le query SQL eseguite. Se SELECT simili si ripetono, è un N+1.
Aggiungi `with()` al codice e ricontrolla le query. Se il numero di query è calato drasticamente, la correzione è completa.
```php theme={null}
// Codice che genera N+1
$posts = Post::all();
foreach ($posts as $post) {
echo $post->user->name; // Query aggiuntiva per ogni post
}
// Risolvi con eager loading
$posts = Post::with('user')->get();
```
Puoi completare tutta la sequenza dal browser senza dover aggiungere `dd()` o log di debug nel codice.
***
## Tracciamento di richieste specifiche con i tag
Telescope ha una funzionalità di **tag**. Con `Telescope::tag()` puoi aggiungere tag arbitrari alle entry e filtrarle rapidamente dal filtro della dashboard.
È molto utile quando vuoi seguire solo le operazioni relative a un certo ID utente o ID ordine.
```php theme={null}
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
// Sovrascrivi il metodo 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 [];
});
```
Ora, digitando `user:42` nella Search della schermata `/telescope/requests`, vedi solo le richieste dell'utente con ID=42.
### Assegnare automaticamente tag ai modelli
Nel metodo `tags` di `TelescopeServiceProvider` puoi assegnare a tutte le entry uno specifico ID di modello.
```php theme={null}
// TelescopeServiceProvider
Telescope::tag(function (IncomingEntry $entry) {
return $entry->tags();
});
```
Implementando inoltre il contract `HasTags` sul modello, quando questo viene registrato vengono assegnati automaticamente i tag.
```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
Usando `dump()`, l'output può mescolarsi nella risposta HTML rendendo difficile il debug delle API. Con il Dump watcher di Telescope puoi separare l'output di `dump()` dalla risposta del browser e registrarlo nella dashboard.
L'uso è semplice: apri il tab "Dump" di `/telescope` e chiama `dump()`.
```php theme={null}
// Controller
public function index()
{
$users = User::with('posts')->get();
dump($users->first()->toArray()); // Compare nel tab dump di Telescope
return response()->json($users);
}
```
La cattura avviene solo con la pagina aperta, quindi puoi monitorare solo quando ti serve. A differenza di `dd()` non blocca l'esecuzione dell'app, quindi è utile per fare debug lasciando fluire più richieste consecutive.
***
## Debug email agevole con l'integrazione Mailpit
Combinando il Mail watcher con il server SMTP locale [Mailpit](https://mailpit.axllent.org/) puoi migliorare notevolmente il flusso di sviluppo delle email.
```ini theme={null}
# .env
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
```
Nel tab Mail di Telescope puoi vedere l'anteprima di HTML e testo delle email inviate. In Mailpit puoi consultare nel browser le email ricevute, verificare gli allegati e controllare lo spam score.
Per evitare invii accidentali a destinatari esterni durante i test, in locale usa sempre un SMTP locale come Mailpit o Mailhog.
***
## Debug di eventi e listener
Il debug di implementazioni event-driven è spesso difficile. Seguire nei log "l'evento si è attivato?" o "quale listener è stato invocato?" è tedioso.
Con l'Events watcher di Telescope vedi in elenco gli eventi emessi e i loro listener.
Se un listener non viene invocato, verifica l'entry dell'evento nel tab Events.
* L'evento è emesso ma non compare il listener → il listener non è registrato (verifica `EventServiceProvider`)
* L'evento stesso non è emesso → verifica il punto di chiamata di `event()`
```php theme={null}
// Flusso per verifica in locale al posto di un test
event(new OrderShipped($order));
// → verifica in /telescope/events che compaia OrderShipped
// → verifica che venga invocato il listener SendShippingConfirmation
```
***
## Debug dei job in coda
Nel debug di elaborazioni asincrone è difficile risalire alla causa guardando solo i log. Il Jobs watcher di Telescope registra dal dispatch del job al risultato dell'esecuzione.
Cliccando sull'entry di un job fallito vedi stack trace e messaggio dell'eccezione. Oltre alla tabella `queue:failed`, la verifica su Telescope permette di individuare rapidamente la causa del fallimento.
```php theme={null}
// Nel debug dei job è più semplice usare il driver sync per l'esecuzione sincrona
// .env
QUEUE_CONNECTION=sync
```
Con il driver sync il job viene eseguito in modo sincrono all'interno della richiesta e il Requests watcher include anche il risultato dell'esecuzione del job.
***
## Debug dei client HTTP
Quando fai debug di comunicazioni con API esterne, l'HTTP Client watcher è utile. Vengono registrate le richieste eseguite tramite la facade `Http::` e le relative risposte.
```php theme={null}
$response = Http::get('https://api.example.com/users');
// → si può controllare in /telescope/client-requests
```
Contenuto della risposta, status code e tempo di esecuzione sono visibili a colpo d'occhio. Puoi consultarli nella dashboard senza scrivere `dd($response->json())`.
***
## Conclusioni
| Tecnica | Vantaggio |
| -------------------- | ----------------------------------------------------------------------- |
| Workflow N+1 | Individua e correggi sistematicamente i problemi delle query senza dd() |
| Tag | Filtra subito i record di uno specifico utente o modello |
| Dump watcher | Verifica l'output di dump senza inquinare la risposta API |
| Integrazione Mailpit | Sviluppo email locale più comodo |
| Events watcher | Verifica visiva dell'emissione di eventi/listener |
| Jobs + sync | Debug dei processi asincroni eseguendoli in sincrono |
| Client HTTP | Registro e verifica delle comunicazioni con API esterne |
Per i dettagli di installazione e configurazione dei watcher fai riferimento alla pagina della guida.
Per il monitoraggio in produzione usa Nightwatch.
## Related topics
- [Introduzione a Laravel Nightwatch](/it/blog/nightwatch-introduction.md)
- [Laravel Telescope](/it/telescope.md)
- [Aggiornamenti Laravel di aprile 2026](/it/blog/changelog/202604.md)
- [Come creare uno starter kit per Laravel](/it/advanced/starter-kit-creation.md)
- [Modalità nativa: Song (sintesi vocale canora) - VOICEVOX for Laravel](/it/packages/laravel-voicevox/native-song.md)