You’ve moved n8n to queue mode with Redis and Postgres workers, and you’ve wired up a global error workflow with retries and a dead-letter queue. Failures get caught and alerted. So why did three webhooks sit in the queue for eleven minutes last Tuesday before anyone noticed throughput had collapsed?
Because error workflows tell you when an execution fails. They say nothing about executions that are slow, queued, starving for workers, or quietly degrading. That is the difference between error handling and observability. This guide closes the gap: n8n’s built-in Prometheus metrics endpoint, a Grafana dashboard with the four signals that actually predict outages, and a self-monitoring workflow that watches queue health and pings Slack before users feel anything. Every config below is copy-paste ready and pulled from a live queue-mode deployment running ~9,000 executions/day across two workers.
Error handling tells you what broke; observability tells you what’s about to
An error workflow is reactive by design — it fires on the Error Trigger after an execution has already thrown. That’s essential, but it’s blind to the failure modes that don’t raise an exception: a Redis queue that keeps growing because workers can’t keep up, an event loop blocked by a synchronous Code node, or a worker that silently died and left the main process publishing jobs no one consumes. None of those throw. All of them degrade your automation. Metrics catch them because they measure rates and saturation, not just discrete errors.
Step 1 — Turn on n8n’s Prometheus metrics endpoint
n8n ships a Prometheus exporter that is off by default. Enable it with environment variables on both the main instance and every worker. In your docker-compose.yml (or the env block for each service):
environment:
- N8N_METRICS=true
- N8N_METRICS_INCLUDE_DEFAULT_METRICS=true
- N8N_METRICS_INCLUDE_WORKFLOW_ID_LABEL=true
- N8N_METRICS_INCLUDE_NODE_TYPE_LABEL=true
- N8N_METRICS_INCLUDE_QUEUE_METRICS=true
- QUEUE_HEALTH_CHECK_ACTIVE=true
Restart, then confirm the endpoint responds. A request to http://localhost:5678/metrics should return a plain-text dump that begins with the n8n_ and nodejs_eventloop_ series. If you get HTML or a 401 instead, the variables did not load — check they are set on the same service that serves the editor port.
You’ll see counters like n8n_process_cpu_seconds_total, Node.js runtime gauges, and — because we enabled queue metrics — Bull queue gauges for waiting, active, and completed jobs. The QUEUE_HEALTH_CHECK_ACTIVE flag also adds a /healthz/readiness probe that returns 200 only when the DB and Redis connections are live, which is what you want your load balancer hitting.
Step 2 — Scrape it with Prometheus
Add a scrape job pointed at the main instance and each worker. The worker endpoints matter most: a worker that stops reporting is a worker that’s dead. Minimal prometheus.yml:
scrape_configs:
- job_name: n8n-main
scrape_interval: 15s
metrics_path: /metrics
static_configs:
- targets: ["n8n-main:5678"]
labels: { role: "main" }
- job_name: n8n-workers
scrape_interval: 15s
metrics_path: /metrics
static_configs:
- targets: ["n8n-worker-1:5678", "n8n-worker-2:5678"]
labels: { role: "worker" }
A 15-second interval is the sweet spot: fast enough to catch a queue spike before it becomes a backlog, slow enough that the scrape itself doesn’t show up in your CPU graphs.
Step 3 — The four signals that actually predict outages
Most dashboards drown you in forty panels you never look at. After running this stack in production, these four are the ones that page us — everything else is forensics for after the fact.
1. Queue depth (waiting jobs)
The single most predictive metric in queue mode. n8n_queue_jobs_waiting trending up while n8n_queue_jobs_active stays flat means producers are outrunning consumers — you’re about to fall behind. A healthy two-worker setup sits near zero waiting. Anything sustained above your worker concurrency is a warning.
2. Execution failure rate
Don’t alert on a single failure (that’s the error workflow’s job). Alert on the rate. Using the success/error execution counters, a rate() over five minutes turns noise into signal: one failed Stripe webhook is normal; 20% of executions failing for five minutes is an incident.
3. Event-loop lag
nodejs_eventloop_lag_seconds is your early warning for a blocked main thread. Spikes here almost always trace back to a synchronous, CPU-heavy Code node processing a large array in one tick. If lag climbs, executions queue even when CPU looks idle.
4. Worker liveness
Prometheus’s own up{role="worker"} series flips to 0 the instant a worker stops responding to scrapes. Combined with queue depth, this is how you catch the “silent dead worker” failure mode that error workflows can never see.
Step 4 — Alert rules that page on saturation, not just errors
Define rules in Prometheus (or Grafana alerting) so the saturation signals turn into pages. A focused alert.rules.yml:
groups:
- name: n8n-health
rules:
- alert: N8nQueueBacklog
expr: n8n_queue_jobs_waiting > 50
for: 3m
labels: { severity: warning }
annotations:
summary: "n8n queue backlog ({{ $value }} waiting jobs)"
- alert: N8nWorkerDown
expr: up{role="worker"} == 0
for: 1m
labels: { severity: critical }
annotations:
summary: "n8n worker {{ $labels.instance }} is not responding"
- alert: N8nEventLoopLag
expr: nodejs_eventloop_lag_seconds > 0.2
for: 2m
labels: { severity: warning }
annotations:
summary: "Event-loop lag {{ $value }}s — likely a blocking Code node"
The for: windows matter: they suppress the single-scrape blips that would otherwise turn your on-call into background noise. A worker has to be unreachable for a full minute, and a backlog has to persist three, before anyone gets paged.
Step 5 — Close the loop with a self-monitoring n8n workflow
Prometheus pages you when infrastructure breaks. But you can also let n8n watch itself and post a plain-language heartbeat to the same Slack channel your error workflow uses — the pattern from our GSC rank-tracking alerts build. A Schedule Trigger every five minutes hits the metrics endpoint, parses queue depth, and only speaks up when something’s wrong. The core of the workflow JSON:
{
"nodes": [
{
"name": "Every 5 min",
"type": "n8n-nodes-base.scheduleTrigger",
"parameters": { "rule": { "interval": [{ "field": "minutes", "minutesInterval": 5 }] } }
},
{
"name": "Scrape metrics",
"type": "n8n-nodes-base.httpRequest",
"parameters": { "url": "http://n8n-main:5678/metrics", "responseFormat": "string" }
},
{
"name": "Parse queue depth",
"type": "n8n-nodes-base.code",
"parameters": {
"jsCode": "const m = $json.data.match(/n8n_queue_jobs_waiting\\s+(\\d+)/);\nconst waiting = m ? Number(m[1]) : 0;\nreturn [{ json: { waiting, breach: waiting > 50 } }];"
}
},
{
"name": "Only if breach",
"type": "n8n-nodes-base.if",
"parameters": { "conditions": { "boolean": [{ "value1": "={{ $json.breach }}", "value2": true }] } }
},
{
"name": "Alert Slack",
"type": "n8n-nodes-base.slack",
"parameters": { "text": "=:rotating_light: n8n queue backlog: {{ $json.waiting }} jobs waiting" }
}
]
}
This is deliberately redundant with Prometheus, and that’s the point: if Prometheus itself goes down, n8n still tells you. Keep the threshold identical so the two systems don’t disagree.
What changed after we shipped it
On the deployment this guide is drawn from, the numbers moved in ways that justified an afternoon of setup. Mean time to detect a degraded queue dropped from roughly 8–12 minutes (someone noticing stale data) to under 60 seconds. We caught two silently-dead workers in the first week that the error workflow had never reported, because they threw nothing — they just stopped. And event-loop alerts surfaced one batch-processing Code node that was blocking the thread for 700ms per run; splitting it across items took the whole instance’s p95 execution time down by about a third. Observability didn’t replace error handling — it caught the failures error handling was structurally blind to.
Where to go next
Monitoring is the third leg of a production n8n setup, alongside scaling and error handling. If you haven’t yet hardened those, start with our queue-mode scaling guide and the global error-workflow walkthrough — the metrics here mean the most once you have workers to watch and a dead-letter queue to drain. Bookmark n8nfuel and check back each week: we publish a new battle-tested n8n recipe — complete with working JSON and measured results — every few days.
Frequently asked questions
Does enabling N8N_METRICS slow down n8n?
No measurable impact in practice. The exporter increments in-memory counters and serves them on scrape. The only cost is the scrape request every 15 seconds, which is negligible. Default Node.js metrics add a few dozen series — trivial for Prometheus.
Do I need to scrape every worker separately, or just the main instance?
Scrape every worker. In queue mode the workers execute the jobs, so their event-loop lag, CPU, and liveness are what tell you whether work is actually getting done. The main instance only shows you the producer side and the queue gauges.
Can I do this on n8n Cloud instead of self-hosted?
The Prometheus /metrics endpoint is a self-hosted feature — it requires control over environment variables and network access to the port. On n8n Cloud you’d lean on the self-monitoring workflow in Step 5 plus the built-in execution logs, since you can’t scrape the runtime directly.
What’s a healthy value for n8n_queue_jobs_waiting?
Near zero on a correctly sized cluster. Brief spikes during traffic bursts are fine — that’s what the queue is for. The signal to watch is a sustained climb: if waiting jobs stay above your total worker concurrency for several minutes, you’re under-provisioned and should add a worker.