> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://nightwatch.laravel.com) è 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.

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

***

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

```mermaid theme={null}
graph TD
    A["Strumenti di monitoraggio Laravel"] --> B["Telescope<br>Debug nell'ambiente di sviluppo"]
    A --> C["Pulse<br>Aggregazione delle performance in produzione"]
    A --> D["Nightwatch<br>Monitoraggio ospitato in produzione"]

    B --> B1["Self-hosted<br>Solo in sviluppo<br>Gratuito, OSS"]
    C --> C1["Self-hosted<br>Dashboard in tempo reale<br>Gratuito, OSS"]
    D --> D1["Piattaforma SaaS<br>Richiede agente residente<br>Servizio a pagamento"]
```

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

```mermaid theme={null}
sequenceDiagram
    participant App as App Laravel
    participant Agent as Agente Nightwatch<br>(php artisan nightwatch:agent)
    participant Cloud as Cloud Nightwatch
    participant Dashboard as Dashboard<br>(nightwatch.laravel.com)

    App->>Agent: Invia dati evento<br>(127.0.0.1:2407)
    Agent->>Cloud: Invio in batch
    Cloud->>Dashboard: Visualizzazione e alert
```

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](https://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

```bash theme={null}
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`.

```ini theme={null}
NIGHTWATCH_TOKEN=your-api-key
```

### 4. Avvio dell'agente

```bash theme={null}
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:

```bash theme={null}
php artisan nightwatch:status
```

### 5. Disattivazione in ambiente di test

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

```ini theme={null}
# .env
NIGHTWATCH_ENABLED=false
```

Puoi configurarlo anche in `phpunit.xml`.

```xml theme={null}
<php>
    <env name="APP_ENV" value="testing"/>
    <env name="NIGHTWATCH_ENABLED" value="false"/>
</php>
```

***

## Configurazione per un uso pratico con il piano gratuito

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

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

```ini theme={null}
# .env
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
```

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

```ini theme={null}
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).

```ini theme={null}
# .env
NIGHTWATCH_IGNORE_QUERIES=true
```

### Altre impostazioni di filtro

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

```ini theme={null}
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

```ini theme={null}
# .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.

```ini theme={null}
# 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.

```ini theme={null}
# 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

```mermaid theme={null}
flowchart TD
    Q1{"Servono dati<br>dell'ambiente di produzione?"} -->|Sì| Q2{"Vuoi mettere i dati<br>sul tuo server?"}
    Q1 -->|No| T["Telescope<br>(sviluppo locale)"]
    Q2 -->|Sì| P["Pulse<br>(self-hosted)"]
    Q2 -->|No| N["Nightwatch<br>(SaaS ospitato)"]
```

* **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](https://nightwatch.laravel.com/docs/start-guide) e il [riferimento delle variabili d'ambiente](https://nightwatch.laravel.com/docs/environment-variables).

<Card title="Tecniche pratiche di Laravel Telescope" icon="telescope" href="/it/blog/telescope-introduction">
  Per il debug in sviluppo locale usa Telescope.
</Card>


## Related topics

- [Introduzione - VOICEVOX for Laravel](/it/packages/laravel-voicevox/getting-started.md)
- [Introduzione - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/getting-started.md)
- [Introduzione a React — le basi per usarlo con Inertia × Laravel](/it/blog/react-introduction.md)
- [Introduzione a Svelte — le basi per usarlo con Inertia × Laravel](/it/blog/svelte-introduction.md)
- [Introduzione a Vue.js — le basi per usarlo con Inertia × Laravel](/it/blog/vue-introduction.md)