Self-Hosted n8n Monitoring: Metrics, Logs, and Alerts
Set up real monitoring for self-hosted n8n: health checks, Prometheus metrics, Grafana dashboards, alert rules, and error workflows that page you before clients notice.

A self-hosted n8n instance fails quietly. A webhook endpoint starts returning 500s at 2 a.m., a credential expires, the execution queue backs up, and the first person to notice is usually your client. The fix is not one tool but three layers: health checks that tell you the instance is alive, Prometheus metrics that tell you how it is behaving, and error workflows that catch individual failures the moment they happen. This guide sets up all three with real configuration, and it is honest about the parts n8n locks behind its Enterprise license.
Everything here applies to self-hosted n8n only. The /metrics endpoint does not exist on n8n Cloud, so if you are on Cloud, skip to the error workflow section and accept that platform-level monitoring is n8n's job, not yours.
Why the executions list is not monitoring
n8n's Executions view shows you what already failed. That is forensics, not monitoring. By the time you open it, the damage is done, and it tells you nothing about problems that never produce an execution: the instance being down, the database being unreachable, or a trigger that stopped firing.
There is also a subtler gap. Workflows that fail at the trigger level produce a different, thinner error payload than workflows that fail mid-run, as the n8n error handling docs note. If your only visibility is the UI, trigger failures are easy to miss entirely.
Production monitoring for n8n has to answer four questions without anyone logging in:
- Is the instance reachable and ready to accept traffic?
- Are executions succeeding at the rate they should?
- Is latency or queue depth trending toward a problem?
- When a specific workflow fails, who gets told, and how fast?
Each layer below answers one or two of those.
Layer 1: health checks and uptime monitoring
n8n exposes two HTTP health endpoints on the main server, described in the Monitor n8n docs:
/healthzreturns 200 when the instance is reachable. It says nothing about the database. An instance can pass/healthzwhile being unable to execute anything./healthz/readinessreturns 200 only when the database is connected and migrated. This is the endpoint that means "ready to accept traffic", and it is the one your load balancer or container orchestrator should gate on.
Two operational details matter here. First, in queue mode the health endpoint on workers is disabled by default; set QUEUE_HEALTH_CHECK_ACTIVE=true on each worker if you want to probe them individually. Second, both endpoints only tell you the instance is up from the inside. They do not tell you whether the outside world can reach it through your reverse proxy, TLS certificate, and DNS.
For that, you want an external black-box probe. Uptime Kuma is the standard self-hosted option: MIT licensed, checks HTTP endpoints at 20-second intervals, and ships notifications through Slack, Telegram, email, and about 90 other services. It runs as a single Docker container:
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2
Point one monitor at https://your-n8n-domain/healthz/readiness and, if you expose public webhooks, a second keyword monitor at a harmless webhook URL so you learn about certificate or proxy breakage before your integrations do. One caveat from the Uptime Kuma docs: do not put its data directory on NFS.
Layer 2: Prometheus metrics and Grafana
Health checks are binary. Metrics are where you see trouble developing. n8n ships a Prometheus /metrics endpoint built on prom-client, but it is disabled by default. Enable it with one environment variable, per the Prometheus metrics docs:
N8N_METRICS=true
The endpoint is available on every self-hosted edition, on both main and worker instances. It is not available on n8n Cloud.
Lock the endpoint down before you scrape it
n8n's own docs warn that /metrics reveals sensitive operational data about your instance. Do not publish it through your public reverse proxy. Bind Prometheus and n8n to a private network, or restrict the path at the proxy level to the Prometheus server's IP. The same principle applies to everything else on the instance; our self-hosted n8n hardening guide covers the full checklist.
Scrape configuration
The Prometheus side is a standard job, from the Grafana visualization docs:
scrape_configs:
- job_name: n8n
metrics_path: /metrics
static_configs:
- targets: ['n8n.internal:5678']
The metrics that actually matter
The default metric set covers process and Node.js internals. The n8n-specific series are opt-in, and the useful ones for alerting are:
- Webhook latency and errors. From n8n 2.28.0,
N8N_METRICS_INCLUDE_WEBHOOK_METRICS=trueexposes ann8n_webhook_request_duration_secondshistogram labelled by method, status code, webhook path, and workflow ID. AddN8N_METRICS_INCLUDE_WORKFLOW_INFO=truefor ann8n_workflow_infogauge that maps IDs to human-readable workflow names, so your dashboards do not read like UUID soup. - Queue depth. In queue mode,
N8N_METRICS_INCLUDE_QUEUE_METRICS=trueexposes Bull queue metrics from the main instance, withN8N_METRICS_QUEUE_METRICS_INTERVALcontrolling refresh. This is your early warning that workers are falling behind. - Scheduler, poll triggers, and system tasks. Separate
N8N_METRICS_INCLUDE_SCHEDULER_METRICS,N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS, andN8N_METRICS_INCLUDE_SYSTEM_TASK_METRICSflags expose scheduling lag, poll errors, and maintenance job health. These matter most on busy instances where a stalled poll trigger means missed data, not just slow data.
You do not have to build dashboards from scratch. n8n maintains an official n8n-observability repository on GitHub with ready-made Grafana dashboards for webhook executions, the durable scheduler, poll triggers, and system tasks, plus a Docker Compose stack that spins up Prometheus and Grafana with everything provisioned. Each dashboard's README lists the exact environment variables it needs.
Alert rules worth running
Metrics without alerts are wallpaper. Prometheus alerting rules evaluate PromQL expressions and hand firing alerts to Alertmanager, which handles grouping, silencing, and routing to Slack or email. Always set a for clause so a single bad scrape does not page you.
A realistic starter set for a production instance:
- Instance down.
up{job="n8n"} == 0for 5 minutes. Severity: page. This is your dead-server alert. - Elevated webhook error rate. Using the docs' error-rate pattern, alert when non-2xx responses exceed 5 percent of webhook traffic over 15 minutes:
sum(rate(n8n_webhook_request_duration_seconds_count{status_code!="2.."}[15m])) / sum(rate(n8n_webhook_request_duration_seconds_count[15m])) > 0.05. Severity: notify during work hours. A burst here usually means an upstream API changed or a credential expired. - High webhook latency.
histogram_quantile(0.95, sum by (le) (rate(n8n_webhook_request_duration_seconds_bucket[5m]))) > 10for 15 minutes. Severity: notify. Slow webhooks time out upstream callers long before they fail. - Queue backing up. With queue metrics enabled, alert when waiting jobs grow for 30 minutes straight. Workers falling behind is how you discover a workflow stuck in a retry loop.
The n8n-observability repo also ships a worked Grafana alerting example that posts to Slack when a single workflow produces more than five failed webhook executions in 30 seconds. That per-workflow alert is worth copying: it catches the "one broken workflow" case that aggregate rates dilute.
Layer 3: catching individual workflow failures
Metrics tell you something is wrong. Error workflows tell you exactly what, in which workflow, with a link to the failed execution.
Any workflow can have an error workflow assigned in its Workflow Settings. The error workflow starts with an Error Trigger node and receives the execution ID, the execution URL, the error message and stack, the last node executed, and the workflow name. One error workflow can serve every workflow on the instance, and the standard pattern is to make it post to a dedicated Slack or Teams channel:
- Error Trigger, then an IF node that drops
mode: manualfailures (you were watching those anyway) - Format a message with workflow name, error message, and the execution URL so the on-call person lands directly on the failed run
- Post to your chat tool of choice
Two behaviours from the error handling docs deserve attention. First, trigger-node failures produce a different payload shape (WorkflowActivationError inside a trigger object) with less detail, so template your messages defensively. Second, the Stop and Error node forces a failure on purpose, which is the right way to fail loudly on bad data instead of writing garbage downstream. Failing loudly only works if the error workflow exists.
Logs and log streaming
n8n logs through winston. The logging docs give you N8N_LOG_LEVEL (default info), N8N_LOG_OUTPUT=console,file, and file rotation via N8N_LOG_FILE_SIZE_MAX (16 MB default) and N8N_LOG_FILE_COUNT_MAX (100 default). Set the file count explicitly when you run workers, because the default exists for a single-process setup. In containers, log to console and let your container platform's log driver handle shipping.
For structured event streaming to external systems, n8n has Log streaming: workflow started/success/failed/cancelled events with execution ID, workflow name, error details, plus audit events like failed logins and credential changes, plus queue events including stalled jobs. Destinations are webhooks, syslog, and Sentry, with a per-destination circuit breaker. The catch: Log streaming is Enterprise-only, on both Cloud and self-hosted. If audit trails and SIEM integration are compliance requirements for you, that is a line item in the licence decision, not a configuration detail.
OpenTelemetry tracing
For deeper visibility, n8n emits OpenTelemetry traces: one workflow.execute span per execution and nested node.execute spans with input and output item counts. You can configure it from Settings, OpenTelemetry without a restart, point it at any OTLP collector, and sample with N8N_OTEL_TRACES_SAMPLE_RATE. In queue mode, set the same variables on mains, workers, and webhook processors, or spans lose their parent context. This is the layer to add when you need to answer "which node in this 40-node workflow is slow", not the layer to start with.
What a sensible setup costs
The software bill is zero. Prometheus, Grafana, Alertmanager, and Uptime Kuma are all open source, and n8n's metrics endpoint needs no licence. The real costs are:
- Infrastructure. Prometheus and Grafana run comfortably alongside n8n on the same small VM for a single-instance setup, or on a separate small VM if you want monitoring to survive the app server dying. Either way this is an incremental cost of one modest host, not a platform purchase.
- Setup time. Budget half a day: enable metrics, deploy the compose stack from the n8n-observability repo, import the dashboards, write four or five alert rules, build the error workflow, and test them by deliberately breaking things.
- The Enterprise gate. Log streaming to a SIEM, and some advanced observability features, require an n8n Enterprise licence. Decide whether your compliance posture needs it before you design around syslog.
If you would rather not own any of this, that is a legitimate choice, and it is exactly the kind of operational work we take over in our managed open-source stack engagements, where monitoring and backups come with the deployment.
Common mistakes
- Exposing
/metricspublicly. It leaks operational detail about your instance. Keep it on a private interface. - Alerting on every failed execution. Some workflows fail daily on bad input and get retried. Alert on rates and thresholds, and route per-execution detail to a low-priority channel via the error workflow.
- No
forclause. Without it, one slow scrape fires a page. Prometheus keeps alerts in a pending state for the duration you set; use it. - Monitoring the main instance but not the workers. In queue mode, workers expose metrics too, and their health endpoint is off by default. The work happens on workers; blind spots there are blind spots everywhere.
- Ignoring execution-data growth. Monitoring will happily watch a database bloat itself to death. n8n prunes execution data by default (
EXECUTIONS_DATA_PRUNE=true,EXECUTIONS_DATA_MAX_AGE=336hours,EXECUTIONS_DATA_PRUNE_MAX_COUNT=10000per the executions configuration docs), but check those settings against your volume before you discover the defaults the hard way. And monitoring is not a substitute for recovery: pair it with a tested n8n backup and restore plan.
When this stack is the wrong choice
If you run one instance with a handful of non-critical workflows, a full Prometheus and Grafana deployment is overkill. The error workflow plus an Uptime Kuma probe gives you 80 percent of the value in an hour. Add metrics when the instance becomes something other people depend on.
If you are on n8n Cloud, most of this guide does not apply: no /metrics, no self-managed Prometheus. Your levers are error workflows, Insights, and, on Enterprise, log streaming.
If your organisation already runs a central observability platform with its own agents and dashboards, do not stand up a parallel Grafana for one application. Scrape n8n into the existing Prometheus, or send traces to the existing collector, and keep alerts in the system people already watch.
Frequently asked questions
Does n8n have built-in monitoring?
Partly. The Executions list, Insights dashboards, and the /healthz and /metrics endpoints are built in, but there is no built-in alerting. You wire notifications yourself through error workflows, Uptime Kuma, or Prometheus alert rules.
Is the /metrics endpoint available on n8n Cloud?
No. According to n8n's docs, /metrics is self-hosted only, on all self-hosted editions. Cloud users get the UI-based tools and, on Enterprise, log streaming.
How do I get alerted when an n8n workflow fails? Create one workflow that starts with an Error Trigger node, have it post the workflow name, error, and execution URL to Slack or email, then set it as the error workflow in every production workflow's settings. It catches failures the moment they happen.
What is the difference between /healthz and /healthz/readiness?
/healthz returns 200 when the instance is reachable but says nothing about the database. /healthz/readiness returns 200 only when the database is connected and migrated. Use readiness for load balancer and orchestrator checks.
How do I monitor n8n workers in queue mode?
Workers expose /metrics when N8N_METRICS=true, and queue-depth metrics come from the main instance with N8N_METRICS_INCLUDE_QUEUE_METRICS=true. Worker health checks need QUEUE_HEALTH_CHECK_ACTIVE=true. Scrape every instance, not just the main.
Does n8n support OpenTelemetry?
Yes. n8n emits workflow.execute and node.execute spans to any OTLP collector over HTTP or gRPC, configurable from Settings without a restart. Sampling and node-level span volume are tunable with environment variables.
Where to go from here
Start with the error workflow and an uptime probe this afternoon; add Prometheus and the official Grafana dashboards when the instance earns them. If you are building client-facing automation on n8n and want the monitoring, scaling, and maintenance handled for you, take a look at our business automation service.
About AI Agents Plus Editorial
AI automation expert and thought leader in business transformation through artificial intelligence.



