Introduzione a Laravel Nightwatch

Panoramica di Nightwatch, la piattaforma SaaS ospitata per il monitoraggio delle applicazioni Laravel, differenze rispetto a Telescope e Pulse, metodo di installazione e configurazione per usarla in modo pratico con il piano gratuito.

​

Cos’è Laravel Nightwatch

Laravel Nightwatch è una piattaforma SaaS ospitata che monitora continuamente l’ambiente di produzione delle applicazioni Laravel. Raccoglie e visualizza in tempo reale i dati di telemetria dell’intera applicazione: richieste HTTP, query SQL, eccezioni, job in coda, log, task pianificati e altro.

Nightwatch è un servizio a pagamento (fatturazione mensile). Puoi usare anche il piano gratuito, ma il numero di eventi raccolti ha un tetto. Per usarlo in modo pratico con il piano gratuito, è indispensabile impostare sampling e filtri come descritto di seguito.

---

​

Differenze rispetto a Telescope e Pulse

Nightwatch ha obiettivi diversi rispetto agli strumenti di monitoraggio e debug esistenti nell’ecosistema Laravel. Riepiloghiamo l’uso di ciascuno.

Strumento	Uso	Hosting	Ambiente di destinazione
Telescope	Debug in sviluppo, ispezione query	Self-hosted (nell’app Laravel)	Sviluppo locale
Pulse	Aggregazione e visualizzazione di metriche di performance	Self-hosted (nell’app Laravel)	Produzione, staging
Nightwatch	Monitoraggio in tempo reale dell’app di produzione	SaaS ospitato da Laravel	Ambiente di produzione

Raccoglie informazioni quasi identiche a Telescope, ma Nightwatch mantiene residente un processo agente che invia i dati al cloud. Puoi quindi consultare i dati storici anche se il server è caduto e gestire in un unico posto più server e applicazioni.

---

​

Architettura

Nightwatch adotta una struttura in cui un processo agente sta tra l’app Laravel e il cloud Nightwatch.

L’agente resta in ascolto in locale (127.0.0.1:2407), riceve gli eventi dell’app Laravel e li inoltra al cloud. Per questo il processo agente deve essere sempre attivo.

---

​

Installazione e configurazione iniziale

​

1. Creazione di account e applicazione

Su nightwatch.laravel.com crea un account e registra organizzazione e applicazione. Dopo la registrazione dell’applicazione viene emesso un token d’ambiente.

​

2. Installazione del pacchetto

composer require laravel/nightwatch

A differenza di Telescope, il flag --dev non è necessario. Nightwatch è pensato per l’uso in produzione.

​

3. Impostazione del token

Aggiungi il token al file .env.

NIGHTWATCH_TOKEN=your-api-key

​

4. Avvio dell’agente

php artisan nightwatch:agent

L’agente deve rimanere in esecuzione in background in modo continuo. Laravel Cloud, Laravel Forge e Laravel Vapor hanno guide dedicate. Con Forge, usando l’integrazione ufficiale, la configurazione è automatica.

Verifica dello stato dell’agente:

php artisan nightwatch:status

​

5. Disattivazione in ambiente di test

Si consiglia di disabilitare Nightwatch durante l’esecuzione dei test.

# .env
NIGHTWATCH_ENABLED=false

Puoi configurarlo anche in phpunit.xml.

<php>
    <env name="APP_ENV" value="testing"/>
    <env name="NIGHTWATCH_ENABLED" value="false"/>
</php>

---

​

Configurazione per un uso pratico con il piano gratuito

Il piano gratuito ha un tetto mensile di eventi. Con la configurazione di default (sampling rate 100% e raccolta di tutti i dati), un’app con molto traffico raggiunge rapidamente il limite. Applica sempre le impostazioni seguenti.

​

Abbassa il sampling rate

NIGHTWATCH_REQUEST_SAMPLE_RATE ha valore predefinito 1.0 (tutte le richieste). Nel piano gratuito si consiglia di limitarlo a circa 0.1 (10%).

# .env
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1

Esempio di configurazione che raccoglie ancora tutti gli eccezioni e i comandi:

NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1    # Richieste: solo 10%
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0  # Eccezioni: tutte (default)
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0    # Comandi: tutti (default)

​

Disabilita la raccolta delle query

Le query al database rappresentano una quota importante degli eventi. Nel piano gratuito, disabilitare la raccolta delle query lascia spazio per eventi più importanti (eccezioni, richieste, job).

# .env
NIGHTWATCH_IGNORE_QUERIES=true

​

Altre impostazioni di filtro

Se necessario, puoi disabilitare anche la raccolta di eventi cache e di email.

NIGHTWATCH_IGNORE_CACHE_EVENTS=true
NIGHTWATCH_IGNORE_MAIL=true
NIGHTWATCH_IGNORE_NOTIFICATIONS=true
NIGHTWATCH_IGNORE_OUTGOING_REQUESTS=true

​

Riepilogo della configurazione consigliata per il piano gratuito

# .env (configurazione consigliata per il piano gratuito)
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_IGNORE_QUERIES=true

Solo con queste tre righe puoi ottenere un monitoraggio applicativo pratico anche con il piano gratuito.

---

​

Funzionalità principali

​

Monitoraggio delle richieste

Raccoglie, per ogni richiesta HTTP, tempo di risposta, status code, informazioni di rotta e altro. Puoi individuare endpoint anomalmente lenti e trovare colli di bottiglia di performance.

​

Tracciamento delle eccezioni

Cattura in tempo reale le eccezioni non gestite in produzione. Stack trace e snippet di codice sorgente vengono registrati automaticamente, semplificando l’indagine.

# Raccolta del codice sorgente delle eccezioni (default abilitato)
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true

​

Raccolta dei log

Si integra con il sistema di log di Laravel (Log::error(), ecc.) e invia log strutturati a Nightwatch.

# Livello minimo di log da raccogliere (default: debug)
NIGHTWATCH_LOG_LEVEL=error

​

Monitoraggio di job e task pianificati

Tiene traccia della cronologia di esecuzione, dello stato di successo/fallimento e del tempo di esecuzione di job in coda e task pianificati. Puoi identificare rapidamente i problemi delle elaborazioni batch.

​

Tracciamento dei deployment

Collega ogni rilascio ai relativi cambiamenti e problemi. Consente indagini visive tipo “dopo questo deploy sono aumentate le eccezioni”.

​

Alert e notifiche

Con l’integrazione Slack o via webhook puoi ricevere notifiche immediate su picchi di eccezioni o degradi di performance.

---

​

Come scegliere tra Telescope e Nightwatch

• Sviluppo locale → Telescope
• Vuoi una dashboard di aggregazione della produzione → Pulse
• Vuoi trace dettagliati e alert per la produzione → Nightwatch

I tre non si escludono a vicenda: puoi usare insieme Pulse e Nightwatch.

---

​

Conclusioni

Laravel Nightwatch è un potente strumento SaaS che aumenta di molto la visibilità sulle app Laravel in produzione. Al momento dell’introduzione, tieni a mente questi punti.

• È necessario mantenere sempre attivo il processo agente
• Per il piano gratuito è di fatto obbligatorio impostare NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1 e NIGHTWATCH_IGNORE_QUERIES=true
• Telescope (sviluppo), Pulse (aggregazione) e Nightwatch (monitoraggio) hanno ruoli diversi e possono coesistere

Per la configurazione dettagliata consulta la documentazione ufficiale e il riferimento delle variabili d’ambiente.

Tecniche pratiche di Laravel Telescope

Per il debug in sviluppo locale usa Telescope.