Selbst gehostetes n8n mit Prometheus und Grafana überwachen

Wenn der n8n-Editor langsamer wird oder ein Webhook länger als üblich braucht, erklärt die Ausführungsliste nur einen Teil des Problems. Ein Metrik-Dashboard zeigt, ob der n8n-Prozess mehr Arbeitsspeicher belegt, mehr CPU verbraucht oder langsamer antwortet.

In diesem Tutorial deployest du n8n und Grafana über Sliplane-Presets und baust anschließend ein kleines Prometheus-Image aus einem GitHub-Repository. Das fertige Dashboard zeigt aktuelle Metriken deiner n8n-Instanz.

Die Einrichtung folgt n8ns offizieller Grafana-Anleitung. Sliplane übernimmt dabei die Container-Deployments. Überwacht werden ein n8n-Prozess und seine Webhooks. Das ersetzt weder n8ns Ausführungsverlauf noch Alarme für Fehler auf Workflow-Ebene.

Was du deployest

Prometheus ruft die n8n-Metriken alle 15 Sekunden ab. Wenn du ein Dashboard öffnest, fragt Grafana die in Prometheus gespeicherten Zeitreihen ab.

Prometheus -- scrapes --> n8n:5678/metrics
Grafana    -- queries --> Prometheus:9090

Deploye alle drei Dienste auf demselben Sliplane-Server. So können sie über interne Hostnamen miteinander kommunizieren. Ein gemeinsames Projekt hilft bei der Organisation, für die Verbindung ist aber der Server entscheidend. Siehe Sliplanes Dokumentation zu privaten Netzwerken.

Diese Anleitung verwendet eine einzelne n8n-Instanz. Wenn n8n bei dir bereits auf Sliplane läuft, beginne mit der Metrikkonfiguration in Schritt 2 und nutze denselben Server für die anderen Dienste.

1. Das n8n-Preset deployen

Du brauchst ein Sliplane-Konto, einen Server mit ausreichend Ressourcen für alle drei Dienste und ein GitHub-Repository für die Prometheus-Konfiguration.

Öffne das n8n-Preset, wähle dein Projekt und deinen Server und prüfe die Deployment-Einstellungen.

n8n deployen >

Lass das persistente Volume des Presets unter /home/node/.n8n eingebunden und sichere den generierten N8N_ENCRYPTION_KEY. n8n benötigt nach einem erneuten Deployment denselben Schlüssel, um gespeicherte Zugangsdaten zu entschlüsseln.

Klicke auf Deploy, warte auf die Verfügbarkeit des Dienstes und öffne seine Sliplane-Domain. Richte das erste Owner-Konto in n8n ein.

Eine ausführlichere Anleitung für diesen Teil findest du unter n8n einfach selbst hosten.

2. Den Metrik-Endpunkt von n8n aktivieren

Öffne die Einstellungen des n8n-Dienstes und füge diese Umgebungsvariable hinzu:

N8N_METRICS=true

Sie aktiviert /metrics. Behalte das Standardpräfix n8n_ für Metriken bei, damit die folgenden Abfragen zu deiner Instanz passen. Diese Einstellungen sind in n8ns Metrikkonfiguration definiert.

Speichere die Einstellungen und warte, bis das erneute Deployment abgeschlossen ist.

Suche und kopiere den internen Hostnamen von n8n in Sliplane. In dieser Anleitung steht n8n-example.internal als Platzhalter dafür. Halte deinen tatsächlichen Hostnamen für den nächsten Schritt bereit.

Die URL zum Abrufen der Metriken sieht so aus:

http://n8n-example.internal:5678/metrics

Interne Adressen sind von Diensten auf demselben Server erreichbar. Im Browser deines Laptops lassen sie sich normalerweise nicht öffnen.

3. Das Prometheus-Image in GitHub erstellen

Erstelle ein GitHub-Repository namens n8n-monitoring. Lege in dessen Stammverzeichnis zwei Dateien an:

n8n-monitoring/
├── Dockerfile
└── prometheus.yml

Dieses Image basiert auf dem offiziellen Prometheus-Image und enthält deine Scrape-Konfiguration. Prometheus beschreibt diesen Ansatz in seiner Anleitung für eigene Images.

Die Scrape-Konfiguration hinzufügen

Erstelle prometheus.yml:

global:
  scrape_interval: 15s
  scrape_timeout: 10s

scrape_configs:
  - job_name: n8n
    metrics_path: /metrics
    scheme: http
    static_configs:
      - targets:
          - "n8n-example.internal:5678"

Ersetze n8n-example.internal durch den aus Sliplane kopierten Hostnamen. Das Ziel enthält nur Host und Port; Protokoll und Pfad haben eigene Einstellungen.

Behalte job_name: n8n bei. Prometheus fügt dieses Job-Label den erfassten Zeitreihen hinzu. Unsere Dashboard-Abfragen verwenden es, um diese Instanz auszuwählen. Intervall und Zielkonfiguration folgen der Prometheus-Konfigurationsreferenz.

Trage hier den Hostnamen direkt ein. Eine Umgebungsvariable im Sliplane-Dienst wird nicht automatisch in static_configs.targets eingesetzt.

Das Dockerfile hinzufügen

Erstelle Dockerfile:

FROM prom/prometheus:v3.14.0

COPY prometheus.yml /etc/prometheus/prometheus.yml

RUN /bin/promtool check config /etc/prometheus/prometheus.yml

ENTRYPOINT ["/bin/prometheus"]
CMD ["--config.file=/etc/prometheus/prometheus.yml", "--storage.tsdb.path=/prometheus", "--storage.tsdb.retention.time=15d", "--storage.tsdb.retention.size=5GB", "--web.listen-address=0.0.0.0:9090"]

Das Beispiel fixiert Prometheus auf v3.14.0, eine veröffentlichte Version auf der Prometheus-Downloadseite. Wähle auch bei Updates einen konkreten Release-Tag.

Der Build führt promtool aus, um Konfigurationsfehler vor dem Start des Images zu erkennen. Prometheus schreibt seine Daten nach /prometheus und lauscht auf Port 9090.

Die Aufbewahrungseinstellungen speichern bis zu 15 Tage Verlauf und löschen ältere Blöcke früher, wenn die Größenschwelle erreicht wird. 5GB ist ein beispielhaftes Budget für die Aufbewahrung, keine harte Grenze für den gesamten Speicherverbrauch: Write-Ahead-Log, aktuelle Daten und Kompaktierung benötigen zusätzlichen Platz. Passe den Wert an den Server an, auf dem auch n8n und Grafana laufen. Siehe Prometheus-Speichereinstellungen.

Committe beide Dateien in den Branch main deines Repositorys. Du kannst sie direkt in der GitHub-Weboberfläche erstellen und committen.

4. Prometheus aus dem Repository deployen

Wähle in deinem Sliplane-Projekt Deploy Service und GitHub als Quelle. Verbinde das gerade erstellte Repository. Falls es nicht in der Liste erscheint, erteile Sliplane Zugriff darauf.

Verwende diese Einstellungen:

Sliplane baut das Image aus deinem Repository und startet den Container. Dieser Ablauf ist in der Anleitung zum GitHub-Deployment beschrieben.

Das Volume erhält den Metrikverlauf über Deployments hinweg. Binde es unter /prometheus ein. Ein Volume unter /etc/prometheus könnte die im Image enthaltene Konfiguration verdecken. Sliplanes Volume-Dokumentation erklärt das Erstellen und Einbinden.

Kopiere den internen Hostnamen, sobald der Dienst läuft. Im Folgenden verwenden wir prometheus-example.internal als Platzhalter.

Wenn du später die Scrape-Konfiguration änderst, committe die aktualisierte prometheus.yml und deploye ein neues Image. Bei aktiviertem Autodeploy deployt Sliplane neue Commits automatisch.

5. Grafana deployen und mit Prometheus verbinden

Öffne das Grafana-Preset und wähle dasselbe Projekt und denselben Server.

Grafana deployen >

Lass das persistente Volume unter /var/lib/grafana eingebunden. Es speichert Grafanas Konfiguration und gespeicherte Dashboards. Deploye den Dienst und öffne anschließend seine Sliplane-Domain.

Bei einem frischen Preset-Deployment ohne eigene Admin-Zugangsdaten meldest du dich mit admin / admin an und änderst das Passwort nach Aufforderung. Siehe die Anleitung zum Sliplane-Grafana-Preset.

In Grafana:

1. Öffne Connections > Data sources.
2. Wähle Add new data source und anschließend Prometheus.
3. Vergib den Namen n8n-prometheus.
4. Setze Prometheus server URL auf http://prometheus-example.internal:9090 und ersetze den Hostnamen durch deinen tatsächlichen Wert.
5. Setze Scrape interval der Datenquelle auf 15s, passend zur prometheus.yml.
6. Wähle Save & test.

Grafana sollte bestätigen, dass es Prometheus abfragen kann. Die Verbindung geht vom Grafana-Server aus, sodass Prometheus privat bleiben kann. Siehe Grafanas Konfiguration der Prometheus-Datenquelle.

Verwende hier nicht localhost:9090. Innerhalb des Grafana-Containers verweist localhost auf diesen Container selbst. Lass auch /metrics in dieser URL weg: Grafana benötigt die Abfrage-API von Prometheus.

6. Prüfen, ob Prometheus n8n-Metriken erfasst

Öffne Explore in Grafana, wähle n8n-prometheus, wechsle im Abfrageeditor zu Code und führe Folgendes aus:

up{job="n8n"}

Der Wert 1 bedeutet, dass der letzte Abruf erfolgreich war. 0 bedeutet, dass Prometheus das Ziel konfiguriert hat, dessen Metriken aber nicht erfolgreich abrufen konnte. Prometheus erklärt diese Metrik in seinem Leitfaden zu Jobs und Instanzen. Ein leeres Ergebnis bedeutet, dass keine passende Zeitreihe vorliegt. Prüfe dann die ausgewählte Datenquelle, den Jobnamen und ob der erste Abruf bereits stattgefunden hat.

Warte nach dem Deployment mindestens zwei Abrufintervalle, bevor du prüfst. Um die verfügbaren n8n-Metriken zu sehen, führe diese Abfrage als Instant Query aus und verwende die Tabellenansicht:

{job="n8n", __name__=~"n8n_.*"}

Diese Prüfung hilft auch, wenn ein importiertes Dashboard leere Panels anzeigt. Welche Metriken verfügbar sind, hängt von deiner n8n-Version und den aktivierten Optionen ab.

7. Dein erstes Dashboard erstellen

Erstelle ein Dashboard über Dashboards > New > New dashboard, wähle Add visualization und anschließend n8n-prometheus.

Beginne mit diesen vier Panels. Wechsle jeweils im Abfrageeditor zu Code, gib die Abfrage ein, wähle Visualisierung und Einheit und kehre zum Dashboard zurück.

Wähle für die Stat-Panels den Abfragetyp Instant, um den aktuellen Wert anzuzeigen. Setze den Zeitraum des Dashboards auf Last 30 minutes, aktiviere eine Aktualisierung alle 15 Sekunden und speichere es als n8n overview.

Die Prozessmetriken stammen aus dem Standard-Collector, den n8n verwendet. Ihre Definitionen findest du in dessen Implementierungen für Arbeitsspeicher, CPU und Prozessstartzeit.

Ein CPU-Wert von 0.5 bedeutet, dass der Prozess im Abfragezeitraum ungefähr einen halben CPU-Kern genutzt hat. Die Speichermetrik zeigt den residenten Arbeitsspeicher des n8n-Prozesses. Sie muss daher nicht dem Gesamtverbrauch entsprechen, den Sliplane für den Container oder Server meldet. Die Laufzeit beginnt bei einem Neustart des n8n-Prozesses wieder von vorn.

Das Panel up zeigt, ob Prometheus Metriken erfassen kann. Ein erfolgreicher Abruf beweist nicht, dass jeder Workflow erfolgreich abgeschlossen wird.

8. Webhook-Metriken hinzufügen

Ab n8n 2.28.0 kannst du auch die Anzahl der Webhook-Anfragen und ihre Antwortzeit visualisieren. Ergänze diese Variable im n8n-Dienst und deploye erneut:

N8N_METRICS_INCLUDE_WEBHOOK_METRICS=true

Erstelle einen kleinen Workflow mit einem Webhook-Trigger, setze den Antwortmodus auf Immediately und veröffentliche ihn, damit seine produktive URL aktiv ist. Rufe diese URL einige Male auf, warte auf den nächsten Prometheus-Abruf und sende weitere Anfragen. Gib Diagrammen mit Ratenberechnungen einige Minuten, um Messpunkte zu sammeln.

Füge ein Zeitreihen-Panel für Anfragen pro Sekunde hinzu:

sum by (workflow_id) (
  rate(n8n_webhook_request_duration_seconds_count{job="n8n"}[$__rate_interval])
)

Erstelle ein weiteres Panel für die p95-Antwortzeit und stelle die Einheit auf Sekunden:

histogram_quantile(
  0.95,
  sum by (le) (
    rate(n8n_webhook_request_duration_seconds_bucket{job="n8n"}[$__rate_interval])
  )
)

Gemessen wird die Zeit zwischen dem Eingang der Webhook-Anfrage und dem Senden der Antwort. Mit Immediately kann der Workflow nach dieser Antwort weiterlaufen. Nutze diese Panels, um das Antwortverhalten der Webhooks zu verstehen. Für die Untersuchung des vollständigen Workflows dienen Ausführungsmetriken oder n8ns Ausführungsverlauf. Das Histogramm und die erforderliche Version sind in n8ns Anleitung zur Webhook-Überwachung dokumentiert.

Lieber ein fertiges Dashboard?

n8n pflegt Dashboard-Vorlagen im Repository n8n-observability. Wähle ein Dashboard, lies in dessen README nach, welche n8n-Version und Umgebungsvariablen erforderlich sind, und lade die JSON-Datei herunter.

Öffne in Grafana Dashboards > New > Import, lade die JSON-Datei hoch und wähle bei Aufforderung n8n-prometheus. Falls das importierte Dashboard auf eine andere Datenquelle verweist, passe es an deine Verbindung an. Die Grafana-Importanleitung beschreibt die verfügbaren Importmethoden.

Beginne auch beim Import einer Vorlage mit den vier grundlegenden Panels von oben. Damit kannst du schnell bestätigen, dass die Erfassung funktioniert, bevor du Fehler bei dashboardspezifischen Metriken suchst.

Fehlerbehebung

Nächste Schritte

Führe nach dem Speichern des Dashboards einen deiner üblichen Workflows aus und beobachte, wie sich die Prozessdiagramme verändern. Halte neben Grafana auch n8ns Ausführungsverlauf geöffnet: Eine Speicherspitze oder höhere CPU-Last gibt dir ein Zeitfenster für die Untersuchung. Der Ausführungsverlauf zeigt, was zu diesem Zeitpunkt lief.

Beobachte die Instanz zunächst ohne zusätzliche Alarme, damit du den normalen CPU- und Speicherverbrauch sowie die übliche Webhook-Latenz kennst. Lege anhand dieser Ausgangswerte Schwellen fest und teste jeden Alarm mit einem kontrollierten Fehler oder einer gezielten Laststeigerung.