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

# Einführung in Laravel Nightwatch

> Überblick über "Nightwatch", die gehostete SaaS-Plattform zur Überwachung von Laravel-Anwendungen. Unterschiede zu Telescope/Pulse, Installationsschritte und Konfigurationen für den praxistauglichen Einsatz im Free-Tarif.

## Was ist Laravel Nightwatch?

[Laravel Nightwatch](https://nightwatch.laravel.com) ist eine **gehostete SaaS-Plattform**, die den produktiven Betrieb von Laravel-Anwendungen kontinuierlich überwacht. Sie erfasst und visualisiert Telemetriedaten der gesamten Anwendung in Echtzeit – HTTP-Requests, SQL-Queries, Exceptions, Queue-Jobs, Logs, Scheduled Tasks u. a.

<Info>
  Nightwatch ist ein **kostenpflichtiger Dienst** (monatliche Abrechnung). Ein Free-Tarif steht zur Verfügung, jedoch mit einer Obergrenze für die erfassbaren Events. Für den praxistauglichen Einsatz im Free-Tarif sind die weiter unten beschriebenen Sampling- und Filter-Einstellungen zwingend nötig.
</Info>

***

## Unterschiede zu Telescope und Pulse

Nightwatch verfolgt einen anderen Zweck als die bestehenden Monitoring- und Debug-Tools im Laravel-Ökosystem. Hier ein Überblick über die jeweiligen Einsatzbereiche.

```mermaid theme={null}
graph TD
    A["Monitoring-Tools von Laravel"] --> B["Telescope<br>Debugging in Entwicklungsumgebungen"]
    A --> C["Pulse<br>Performance-Aggregation im Produktivbetrieb"]
    A --> D["Nightwatch<br>gehostete Überwachung im Produktivbetrieb"]

    B --> B1["selbst gehostet<br>nur für die Entwicklung<br>kostenlos, Open Source"]
    C --> C1["selbst gehostet<br>Echtzeit-Dashboard<br>kostenlos, Open Source"]
    D --> D1["SaaS-Plattform<br>Agent-Prozess erforderlich<br>kostenpflichtiger Dienst"]
```

| Tool           | Zweck                                            | Hosting                                    | Zielumgebung        |
| -------------- | ------------------------------------------------ | ------------------------------------------ | ------------------- |
| **Telescope**  | Debugging und Query-Analyse in der Entwicklung   | selbst gehostet (in der Laravel-Anwendung) | Lokale Entwicklung  |
| **Pulse**      | Aggregation und Anzeige von Performance-Metriken | selbst gehostet (in der Laravel-Anwendung) | Produktion, Staging |
| **Nightwatch** | Echtzeit-Monitoring von Produktions-Apps         | von Laravel gehostetes SaaS                | Produktion          |

Es werden nahezu dieselben Informationen wie bei Telescope gesammelt. Nightwatch lässt jedoch einen Agenten-Prozess resident laufen, der die Daten in die Cloud sendet. Dadurch bleiben historische Daten auch bei Serverausfällen einsehbar, und mehrere Server und Anwendungen lassen sich zentral verwalten.

***

## Architektur

Nightwatch schaltet einen Agent-Prozess zwischen die Laravel-Anwendung und die Nightwatch-Cloud.

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

    App->>Agent: Event-Daten senden<br>(127.0.0.1:2407)
    Agent->>Cloud: Batch-Übertragung
    Cloud->>Dashboard: Visualisierung, Alerts
```

Der Agent lauscht lokal (`127.0.0.1:2407`), empfängt Events aus der Laravel-Anwendung und leitet sie in die Cloud weiter. Der Agent-Prozess muss deshalb dauerhaft laufen.

***

## Installation und Erst-Konfiguration

### 1. Account und Anwendung anlegen

Erstellen Sie unter [nightwatch.laravel.com](https://nightwatch.laravel.com) einen Account und registrieren Sie Organisation und Anwendung. Nach der Registrierung der Anwendung wird ein **Umgebungs-Token** ausgegeben.

### 2. Paket installieren

```bash theme={null}
composer require laravel/nightwatch
```

Anders als bei Telescope ist das Flag `--dev` **nicht** erforderlich. Nightwatch ist auf den Einsatz in der Produktion ausgelegt.

### 3. Token konfigurieren

Fügen Sie den Token in der `.env`-Datei hinzu.

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

### 4. Agenten starten

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

Der Agent muss dauerhaft im Hintergrund laufen. Für Laravel Cloud, Laravel Forge und Laravel Vapor stehen jeweils eigene Anleitungen zur Verfügung. Bei Forge wird per offizieller Integration automatisch konfiguriert.

Status des Agenten prüfen:

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

### 5. Deaktivierung in der Testumgebung

Für Test-Läufe empfiehlt es sich, Nightwatch zu deaktivieren.

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

Alternativ per `phpunit.xml`:

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

***

## Konfiguration für den praxistauglichen Einsatz im Free-Tarif

<Warning>
  **Der Free-Tarif hat eine monatliche Event-Obergrenze.** Mit den Default-Einstellungen (Sampling-Rate 100 %, vollständige Erfassung) ist die Grenze in traffic-starken Anwendungen schnell erreicht. Wenden Sie die folgenden Einstellungen unbedingt an.
</Warning>

### Sampling-Rate reduzieren

`NIGHTWATCH_REQUEST_SAMPLE_RATE` ist standardmäßig `1.0` (alle Requests werden erfasst). Im Free-Tarif wird eine Reduktion auf etwa `0.1` (10 %) empfohlen.

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

Beispiel, bei dem Exceptions und Kommandos weiterhin vollständig erfasst werden:

```ini theme={null}
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1    # Requests: nur 10 %
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0  # Exceptions: alle (Default)
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0    # Kommandos: alle (Default)
```

### Query-Erfassung deaktivieren

Datenbank-Queries machen oft einen großen Anteil der Events aus. Wenn Sie die Query-Erfassung im Free-Tarif deaktivieren, bleibt Kapazität für wichtige Events (Exceptions, Requests, Jobs) frei.

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

### Weitere Filter-Einstellungen

Bei Bedarf lassen sich auch Cache-Events und Mails deaktivieren.

```ini theme={null}
NIGHTWATCH_IGNORE_CACHE_EVENTS=true
NIGHTWATCH_IGNORE_MAIL=true
NIGHTWATCH_IGNORE_NOTIFICATIONS=true
NIGHTWATCH_IGNORE_OUTGOING_REQUESTS=true
```

### Empfohlene Konfiguration für den Free-Tarif

```ini theme={null}
# .env (Empfehlung für den Free-Tarif)
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_IGNORE_QUERIES=true
```

Mit diesen drei Zeilen erreichen Sie auch im Free-Tarif ein praxistaugliches Application-Monitoring.

***

## Wichtige Funktionen

### Request-Monitoring

Pro HTTP-Request werden Response-Zeit, Statuscode, Route-Informationen u. a. erfasst. So identifizieren Sie ungewöhnlich langsame Endpunkte und finden Performance-Engpässe.

### Exception-Tracking

Unhandled Exceptions in der Produktion werden in Echtzeit erfasst. Stacktrace und Codeausschnitte werden automatisch protokolliert; die Ursachenanalyse wird deutlich einfacher.

```ini theme={null}
# Quellcode-Erfassung für Exceptions (per Default aktiv)
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true
```

### Log-Erfassung

Integration mit dem Logging-System von Laravel (z. B. `Log::error()`), strukturierte Logs werden an Nightwatch gesendet.

```ini theme={null}
# Minimalstufe der erfassten Logs (Default: debug)
NIGHTWATCH_LOG_LEVEL=error
```

### Monitoring von Jobs und Scheduled Tasks

Ausführungsverlauf, Erfolg/Fehlschlag und Laufzeit von Queue-Jobs und Scheduled Tasks werden nachverfolgt. Probleme in Batch-Verarbeitung lassen sich schnell aufspüren.

### Deployment-Tracking

Verknüpfung von Änderungen pro Release mit auftretenden Problemen. Analysen wie „Seit diesem Deployment nehmen die Exceptions zu" werden visuell möglich.

### Alerts und Benachrichtigungen

Per Slack-Integration und Webhooks lassen sich Spitzenlasten bei Exceptions oder Performance-Verschlechterungen sofort melden.

***

## Wann Telescope, wann Nightwatch?

```mermaid theme={null}
flowchart TD
    Q1{"Daten aus der<br>Produktion nötig?"} -->|Ja| Q2{"Daten auf eigenem<br>Server behalten?"}
    Q1 -->|Nein| T["Telescope<br>(lokale Entwicklung)"]
    Q2 -->|Ja| P["Pulse<br>(selbst gehostet)"]
    Q2 -->|Nein| N["Nightwatch<br>(gehostetes SaaS)"]
```

* **Lokale Entwicklung** → Telescope
* **Aggregations-Dashboard für die Produktion gewünscht** → Pulse
* **Detaillierte Traces und Alerts in der Produktion gewünscht** → Nightwatch

Die drei schließen sich nicht aus – Pulse und Nightwatch lassen sich auch parallel einsetzen.

***

## Fazit

Laravel Nightwatch ist ein leistungsstarkes SaaS-Tool, das die Sichtbarkeit produktiver Laravel-Anwendungen erheblich steigert. Bei der Einführung sollten Sie folgende Punkte beachten:

* Der Agent-Prozess muss dauerhaft laufen
* Im Free-Tarif sind `NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1` und `NIGHTWATCH_IGNORE_QUERIES=true` praktisch unverzichtbar
* Telescope (Entwicklung), Pulse (Aggregation) und Nightwatch (Monitoring) erfüllen unterschiedliche Rollen und lassen sich kombinieren

Für detaillierte Konfigurationen konsultieren Sie die [offizielle Dokumentation](https://nightwatch.laravel.com/docs/start-guide) und die [Referenz der Umgebungsvariablen](https://nightwatch.laravel.com/docs/environment-variables).

<Card title="Praxis-Techniken zu Laravel Telescope" icon="telescope" href="/de/blog/telescope-introduction">
  Für Debugging in der lokalen Entwicklung setzen Sie Telescope ein.
</Card>


## Related topics

- [laravel/agent-skills – Offizielle KI-Agent-Skills-Sammlung von Laravel](/de/blog/agent-skills-introduction.md)
- [Laravel Cloud – Der Gesamtüberblick zum Laravel-eigenen PaaS](/de/blog/laravel-cloud.md)
- [Einführung in Eloquent](/de/eloquent.md)
- [Einführung in die Authentifizierung](/de/authentication.md)
- [Einführung in Eloquent-Relationen](/de/eloquent-relationships.md)