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

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.

---

​

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.

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.

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 einen Account und registrieren Sie Organisation und Anwendung. Nach der Registrierung der Anwendung wird ein Umgebungs-Token ausgegeben.

​

2. Paket installieren

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.

NIGHTWATCH_TOKEN=your-api-key

​

4. Agenten starten

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:

php artisan nightwatch:status

​

5. Deaktivierung in der Testumgebung

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

# .env
NIGHTWATCH_ENABLED=false

Alternativ per phpunit.xml:

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

---

​

Konfiguration für den praxistauglichen Einsatz im Free-Tarif

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.

​

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.

# .env
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1

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

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.

# .env
NIGHTWATCH_IGNORE_QUERIES=true

​

Weitere Filter-Einstellungen

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

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

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

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

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

• 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 und die Referenz der Umgebungsvariablen.

Praxis-Techniken zu Laravel Telescope

Für Debugging in der lokalen Entwicklung setzen Sie Telescope ein.