Monitoraggio di una web app con Laravel Telescope

Quando si costruiscono applicazioni web, è quasi impossibile evitare di incontrare dei bug. Basta dimenticarsi una virgola, un punto e virgola, rinominare o spostare una funzione. Per risolverli velocemente occorre avere un'idea chiara di tutto quello che avviene nella vostra applicazione, come e quando accade. Avere accesso a queste informazioni ti dà molto più controllo nel restringere i bug e identificare le opportunità per migliorare la tua applicazione.

Laravel Telescope ti dà esattamente questo potere. Si tratta di un incredibile strumento di debug recentemente introdotto in Laravel, che semplifica lo sviluppo con strumenti che ti permettono non solo di monitorare ed eseguire il debug di vari aspetti della tua applicazione, ma anche di avere accesso a una vasta gamma di informazioni a cui normalmente non avresti accesso diretto.

Laravel Telescope fornisce approfondimenti sulle richieste che arrivano nella vostra applicazione, eccezioni, voci di registro, query al database, code di lavoro, posta, notifiche, cache e molto altro. Mostra anche come le diverse parti dell'applicazione lavorano insieme. Puoi scoprire quali pagine stanno lavorando correttamente e quali query sono state eseguite quando una richiesta è stata fatta a una certa pagina.

In questo articolo, ti mostrerò alcune caratteristiche di Telescope, come impostarlo e cosa può fare per te.

Alternative precedenti

Se il debug in Laravel non ti è estraneo, allora è probabile che tu abbia usato i seguenti strumenti in passato per soddisfare le tue esigenze di debug.

Laravel Debugbar

Laravel Debugbar aggiunge una piccola barra nella parte inferiore del browser con informazioni di debug (ad esempio il numero di query). Con Eloquent può essere facile fare richieste inutili al database (es. N+1 queries), Debugbar ci aiuta a identificare il codice che non è performante. Lo visualizza proprio accanto alla console dello sviluppatore nella parte inferiore del browser.

Log di Laravel

Un altro metodo per effettuare il debug è quello di accedere (direttamente o con qualche viewer) ai log di Laravel. Bello ma non certo comodo. E in produzione loggare troppe info può creare qualche fastidio.

Come funziona Laravel Telescope?

Laravel Telescope fornisce un'interfaccia utente molto potente per visualizzare, monitorare e fare il debug di vari aspetti della tua applicazione. Dalle richieste ai comandi eseguiti nel terminale e persino ai jobs schedulati. Lo fa attraverso molteplici watcher che sono stati configurati per monitorare queste cose.

I watcher sono stati progettati per raccogliere informazioni su ogni richiesta che arriva nella vostra applicazione, fornire informazioni sulle query al database, quanto tempo impiegano per essere eseguite, le eccezioni incontrate, gli eventi, le code, i comandi e altro ancora.

Installazione

Laravel Telescope è stato introdotto circa 2 anni fa con Laravel 5.7. Con versioni precedenti quindi, non può funzionare. (Vuoi fare un upgrade della tua app ma non sai da dove partire? Ho scritto un articolo introduttivo)

Una volta che hai la tua applicazione Laravel a posto, puoi installare Telescope attraverso composer eseguendo:

composer require laravel/telescope

Puoi anche specificare durante l'installazione se vuoi che funzioni solo nel tuo ambiente di sviluppo usando il flag --dev. Per farlo, dovrai eseguire:

composer require laravel/telescope --dev

Una volta fatto, puoi pubblicare le risorse di Telescope ed eseguire le migrazioni:

php artisan telescope:install
php artisan migrate

Laravel viene fornito con due migrazioni già pronte per te, la tabella users e la tabella password_resets. Quando si esegue la migrazione, vengono create anche tre tabelle che gestiscono le operazioni di Telescope e cioè: telescope_entries, telescope_entries_tags e telescope_monitoring.

Caratteristiche

Ora che abbiamo installato e configurato Telescope, visitando la url /telescope sul nostro progetto, arriveremo direttamente alla dashboard di Telescope da dove potremo passare da una scheda all'altra per monitorare le varie funzionalità. Le funzionalità monitorabili sono: Requests, Commands, Jobs, Cache, Dumps, Events, Exceptions, Gates, Logs, Mail, Models, Notifications, Queries, Redis e le Views.

Ogni caratteristica elencata ha la sua pagina e il suo watcher impostati in Telescope. Ora andremo a vedere cosa ci permette di monitorare ognuna di esse e i dettagli che fornisce.

Requests

Questa sezione elenca tutte le richieste HTTP che entrano nella vostra applicazione e il tempo in cui la richiesta è stata fatta. Fornisce anche informazioni aggiuntive su ogni singola request cliccando sull'icona con l'occhio a destra di ogni voce.

Per ogni richiesta effettuata, si è anche in grado di visualizzare i dati correlati da altri watcher. Per esempio, ho eseguito una rapida query per recuperare tutti gli utenti sulla homepage e questo viene mostrato nelle richieste insieme a quanto tempo è durata la query. Queste informazioni aggiuntive non sono limitate alle sole query e possono mostrare informazioni su qualsiasi altro osservatore che è stato attivato dalla richiesta.

Commands

Telescope non si limita solo alle azioni nel browser o alle richieste, ma copre anche i comandi Artisan eseguiti nel terminale. La pagina dei comandi elenca tutti i comandi che sono stati eseguiti nel terminale e mostra se hanno avuto successo usando i loro codici di uscita: di solito 0 per quando ha funzionato correttamente e un numero che va da 1 a 255 se è stato incontrato un altro risultato. Un esempio, come mostrato sotto, mostra i dettagli del comando php artisan inspire eseguito nel terminale.

Schedule

Come saprai, invece di avere più voci cron per ogni compito schedulato sul tuo server, Laravel fornisce uno scheduler che ti permette di definire comandi e job direttamente dall'app Laravel. La pagina Schedule elenca tutti i comandi programmati che sono stati eseguiti, fornendo informazioni su quando è successo e la pianificazione cron. Nell'esempio ho schedulato il comando inspire per essere eseguito ogni ora.

Jobs

Questa pagina elenca tutti i jobs che sono stati eseguiti e il loro stato. Nella pagina dei dettagli dei jobs, puoi vedere il numero di tentativi, i timeout, la coda e il nome della classe del job eseguito, ecc.

PS: se volete monitorare Redis, l'ecosistema Laravel mette a disposizione Horizon, che magari vedremo assieme più avanti.

Caches

La pagina della cache mostra una lista di cache hit, miss, aggiornamento ecc. Si può vedere la richiesta che l'ha innescata e molto altro.

Dumps

La maggior parte delle volte, quando mi trovo di fronte ad un bug, voglio solo vedere lo stato attuale delle variabili o degli oggetti o qualsiasi altra informazione sullo schermo usando il metodo dump() (se usi il comando dd(), il dump viene reindirizzato ma il die viene eseguito lo stesso). Facendo questo normalmente la formattazione della pagina viene un po' distorta, ma con Telescope, se usate il metodo dump() nel vostro codice, e avete la pagina Dumps aperta in Telescope, la vostra pagina apparirà normale e l'output dei dati apparirà invece nella pagina Dumps.

Events

Questa pagina mostra una lista di tutti gli eventi con informazioni aggiuntive ad accompagnarli. Compresi il tempo, i listeners e quali eventi sono stati trasmessi con un tag.

Exceptions

Con Telescope, le eccezioni sono facili da gestire. Questa pagina elenca tutte le eccezioni e il numero di volte che si sono verificate.

Passando alla pagina dei dettagli, vi mostra il messaggio di errore esatto, quale linea del vostro codice l'ha causato e persino lo stack trace completo che è formattato in modo ordinato e piacevole da guardare. Una volta fixata, potrete anche segnarla come corretta.

Gates

Se sai cosa sono i gates e le policy, saprai anche cosa aspettarti da questa sezione: tutti i controlli dei permessi verificati dalla tua applicazione.

Logs

Qui ci verranno mostrati i messaggi di log, il livello e l'ora in cui ciascuno di essi si è verificato. Come tutte le altre pagine, la pagina di dettaglio mostra più informazioni, compresi i dati del contesto che potresti aver passato. Questo è molto meglio che dover scorrere i file di log, no?

Mail

Questa sezione mostra una lista di tutte le email inviate, a chi è stata inviata, l'ora in cui è stata inviata, l'oggetto e anche l'anteprima dell'email.

Models

Qui viene tenuta traccia di tutte le attività che avvengono con i tuoi modelli. Il modello User viene fornito di default con Laravel. Quindi, come esempio, ogni azione intrapresa sul modello User apparirà in questa pagina. Da quando crei un nuovo utente o anche l'aggiornamento del profilo dell'utente, tutto viene registrato.

Notifications

Questa sezione mostra un elenco delle notifiche, i canali su cui sono state create, l'ora e chi era il destinatario della notifica.

Queries

La pagina delle query funziona molto come la Debugbar menzionata sopra. Elenca tutte le tue query al database, quanto tempo hanno impiegato, su quali richieste, ecc. Puoi facilmente usare questa pagina per impostare un parametro di riferimento per quali delle tue query sono considerate lente una volta che impiegano più di un tempo specifico. Puoi anche impostare questo in config/telescope.php.

Redis

La pagina redis è molto simile alla pagina della cache. Ti mostra quanto tempo ci è voluto, quando è successo e la richiesta che l'ha scatenato.

Views

Conclude l'elenco delle caratteristiche monitorabili. Qui si vedono tutte le views visualizzate con i relativi dati passati dal controller.

Configurazione aggiuntiva

Telescope pubblica un file di configurazione in config/telescope.php che si può usare per settare le varie opzioni e il percorso dei watcher. Ognuna di queste configurazioni è accompagnata da una descrizione del suo scopo che rende facile capire cosa è destinato a fare.

Per esempio, si può cambiare il path da cui accedere a Telescope, /telescope di default.

Pruning del database

Come puoi immaginare, tutte queste informazioni vengono salvate sul DB. Per evitare di saturare lo spazio è necessario quindi abilitare un pruning dei dati. Telescope ci viene in aiuto con un comando artisan da aggiungere al metodo schedule del file console/Kernel.php:

$schedule->command('telescope:prune')->daily();

In questo modo verranno conservati solo i log delle ultime 24 ore. Se volessimo un periodo di retention diverso, possiamo usare il parametro --hours:

$schedule->command('telescope:prune --hours=48')->daily();