Tecniche pratiche di Laravel Telescope

Per l’installazione e la configurazione di base fai riferimento alla pagina della guida. 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 o Laravel Nightwatch.

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.

Trova le richieste lente in Requests

Apri /telescope e individua nel tab Requests le richieste con tempo di esecuzione elevato.

Verifica in Queries l'SQL emesso

Aprendo il dettaglio della richiesta vedi tutte le query SQL eseguite. Se SELECT simili si ripetono, è un N+1.

Aggiungi eager loading e correggi

Aggiungi with() al codice e ricontrolla le query. Se il numero di query è calato drasticamente, la correzione è completa.

// 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.

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.

// 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.

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().

// 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 puoi migliorare notevolmente il flusso di sviluppo delle email.

# .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()

// 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.

// 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.

$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

Guida a Laravel Telescope

Per i dettagli di installazione e configurazione dei watcher fai riferimento alla pagina della guida.

Laravel Nightwatch

Per il monitoraggio in produzione usa Nightwatch.

​Scoprire il problema N+1 in modo sistematico

​Tracciamento di richieste specifiche con i tag

​Assegnare automaticamente tag ai modelli

​Uso del Dump watcher

​Debug email agevole con l’integrazione Mailpit

​Debug di eventi e listener

​Debug dei job in coda

​Debug dei client HTTP

​Conclusioni

Guida a Laravel Telescope

Laravel Nightwatch

Scoprire il problema N+1 in modo sistematico

Tracciamento di richieste specifiche con i tag

Assegnare automaticamente tag ai modelli

Uso del Dump watcher

Debug email agevole con l’integrazione Mailpit

Debug di eventi e listener

Debug dei job in coda

Debug dei client HTTP

Conclusioni