Monitoring: Logs, Healthchecks, Prometheus/Grafana

Wer eine n8n-Instanz selbst betreibt, braucht für einen verlässlichen Betrieb drei Bausteine: aussagekräftige Logs zur Fehlersuche, einen Healthcheck-Endpunkt für das Uptime-Monitoring und Prometheus-Metriken für tiefere Einblicke in Warteschlangen, Webhooks und Formulare. n8n bringt alle drei Bausteine bereits mit, sie müssen nur über Umgebungsvariablen aktiviert und angebunden werden. Stand: Juli 2026.

Log-Level und Log-Ausgabe konfigurieren

n8n nutzt die Logging-Bibliothek winston und stellt die Log-Ausgabe laut der n8n-Dokumentation zum Logging über Umgebungsvariablen ein. Für den Alltag reichen zwei Einstellungen.

• N8N_LOG_LEVEL: steuert die Ausführlichkeit. Von niedrig nach hoch stehen silent, error, warn, info und debug zur Verfügung, Standard ist info. silent gibt gar nichts aus, debug liefert die ausführlichste Diagnoseinformation und eignet sich vor allem für die gezielte Fehlersuche.
• N8N_LOG_OUTPUT: legt fest, wohin geloggt wird, console oder file, auch kombiniert als console,file. Standard ist console.
• N8N_LOG_FILE_LOCATION: Pfad der Log-Datei, wenn file aktiv ist. Standard ist <n8n-Ordner>/logs/n8n.log.
• N8N_LOG_FILE_SIZE_MAX: maximale Größe je Log-Datei in MB, Standard 16 MB.
• N8N_LOG_FILE_COUNT_MAX: maximale Anzahl aufbewahrter Log-Dateien, Standard 100. Bei mehreren Workern sollte dieser Wert bewusst gesetzt werden, damit die Rotation zum Speicherplatz passt.

Für die Produktion ist info in der Regel ausreichend, debug bleibt eine temporäre Maßnahme, weil es spürbar mehr Daten schreibt und die Log-Dateien schneller füllt.

Healthcheck-Endpunkte für Uptime-Monitoring

Laut der n8n-Dokumentation zum Monitoring stellt n8n zwei Health-Endpunkte bereit, die sich für externe Uptime-Checks eignen. Der Endpunkt /healthz meldet lediglich, ob die Instanz erreichbar ist, ein HTTP-200 sagt nichts über den Datenbankstatus aus. Der Endpunkt /healthz/readiness geht weiter: Er liefert erst dann 200, wenn die Datenbank verbunden und migriert ist, die Instanz also tatsächlich bereit ist, Anfragen zu verarbeiten. Der Pfad lässt sich über die Variable N8N_ENDPOINT_HEALTH anpassen, etwa wenn ein Reverse Proxy einen anderen Health-Pfad erwartet.

Auf dem Hauptserver ist der Health-Endpunkt immer aktiv. Bei Worker-Instanzen im Queue-Modus ist er dagegen standardmäßig deaktiviert und muss über QUEUE_HEALTH_CHECK_ACTIVE=true eingeschaltet werden, wenn ein Loadbalancer oder Orchestrator auch die Worker prüfen soll.

Prometheus-Metriken exportieren

Für detailliertere Betriebsdaten stellt n8n über die Bibliothek prom-client einen /metrics-Endpunkt bereit. Er ist standardmäßig deaktiviert und wird mit N8N_METRICS=true aktiviert, sowohl auf main- als auch auf worker-Instanzen. Wichtig für den Betrieb: Der Endpunkt sollte nicht öffentlich erreichbar sein, sondern nur für interne Systeme, die die Prometheus-Daten konsumieren, da er operative Details der Instanz preisgibt.

Welche Metriken und Labels konkret ausgegeben werden, steuern die N8N_METRICS_INCLUDE_*-Variablen. Für Skalierungs-Setups im Queue-Modus liefert N8N_METRICS_INCLUDE_QUEUE_METRICS=true Kennzahlen wie n8n_scaling_mode_queue_jobs_active, _completed, _failed und _waiting, die Aktualisierungsrate lässt sich über N8N_METRICS_QUEUE_METRICS_INTERVAL anpassen. Seit n8n 2.28.0 lassen sich zusätzlich Webhook- und Formular-Laufzeiten erfassen: N8N_METRICS_INCLUDE_WEBHOOK_METRICS aktiviert das Histogramm n8n_webhook_request_duration_seconds, N8N_METRICS_INCLUDE_FORM_METRICS das Pendant n8n_form_submission_duration_seconds für Formularabsendungen. Mit N8N_METRICS_INCLUDE_WORKFLOW_INFO lässt sich zusätzlich ein Gauge n8n_workflow_info aktivieren, der Workflow-IDs mit lesbaren Namen verknüpft, praktisch für Grafana-Panels ohne kryptische IDs.

Metriken mit Grafana visualisieren

Sind die Metriken aktiviert, übernimmt Prometheus das Einsammeln über einen Scrape-Job, der regelmäßig den /metrics-Pfad der n8n-Instanz abfragt, standardmäßig läuft n8n auf Port 5678. Grafana wird anschließend als Datenquelle mit der Prometheus-Serveradresse verbunden. Für den Einstieg müssen keine Dashboards von Grund auf gebaut werden: n8n veröffentlicht im GitHub-Projekt n8n-observability fertige Grafana-Dashboards für die unterstützten Metriken, darunter auch für Webhook- und Formular-Laufzeiten.

Wichtig für die Einordnung: Der /metrics-Endpunkt steht nur bei Self-Hosted-Instanzen zur Verfügung, bei n8n Cloud ist er nicht verfügbar. Wer produktiv mit Self-Hosting und eigener Prozesshoheit arbeiten will, findet dazu Unterstützung bei der n8n-Beratung von NordFlux.

Häufige Fragen zu Monitoring in n8n

Ist der /metrics-Endpunkt bei n8n Cloud verfügbar?

Nein, der Prometheus-Metriken-Endpunkt ist laut n8n-Dokumentation ausschließlich für Self-Hosted-Instanzen vorgesehen. Bei Cloud-Instanzen steht er nicht zur Verfügung.

Welches Log-Level eignet sich für den Produktivbetrieb?

Der Standardwert info liefert im Regelfall ausreichend Kontext für den laufenden Betrieb. debug erzeugt deutlich mehr Ausgabe und eignet sich vor allem, um eine konkrete Störung gezielt und zeitlich begrenzt zu untersuchen.

Wie überwache ich Worker in einem Queue-Mode-Setup?

Der Health-Endpunkt ist bei Worker-Instanzen im Queue-Modus standardmäßig deaktiviert und muss über QUEUE_HEALTH_CHECK_ACTIVE=true aktiviert werden. Ergänzend liefert N8N_METRICS_INCLUDE_QUEUE_METRICS=true Kennzahlen zu aktiven, abgeschlossenen, fehlgeschlagenen und wartenden Jobs in der Warteschlange.

Brauche ich zwingend Grafana, um n8n zu überwachen?

Nein. Für ein einfaches Uptime-Monitoring reicht der /healthz- beziehungsweise /healthz/readiness-Endpunkt, den viele Monitoring-Tools direkt per HTTP-Check abfragen können. Grafana wird erst relevant, wenn detaillierte Verläufe, Warteschlangen- oder Latenzdaten aus dem /metrics-Endpunkt grafisch ausgewertet werden sollen.