Monitoring a self-hosted n8n instance: healthz, metrics and alerts

A self-hosted n8n instance running for months without monitoring is an outage waiting for its moment: a disk filled up by execution data, a container that stayed down after a server reboot, scheduled workflows that no longer fire — and nobody notices until someone asks why the weekly report never arrived. Monitoring an n8n instance comes down to three complementary layers: instance availability, execution health, and metrics over time. None of the three replaces the others.

Layer 1: instance availability

The /healthz endpoint

n8n natively exposes a healthcheck endpoint: https://your-instance/healthz. As long as the instance is operational, it responds with a 200 status. It's the entry point for all monitoring — the one polled by orchestrators (Docker healthchecks, Kubernetes probes) and external probes alike.

An external uptime probe, necessarily outside your server

The essential reflex: have /healthz polled every minute by an external monitoring service — UptimeRobot, Better Stack, or any equivalent, whose free tiers are more than enough for one instance. The important word is external: a probe hosted on the same server as n8n goes down with it. If the whole server disappears (hosting outage, full disk, frozen kernel), only an outside observer can notice and alert you.

Why an Error Workflow does not detect a downed instance

This is the most common misunderstanding. An Error Workflow is triggered by n8n itself when an execution fails. If the entire instance is offline, nothing runs anymore — neither your workflows, nor the Error Workflow supposed to warn you. The silence is then total, and that's precisely the worst-case scenario: scheduled triggers missed during downtime are not caught up. The Error Workflow monitors executions; the external probe monitors the instance. You need both.

Layer 2: execution health

The global Error Workflow

Once availability is covered, the question becomes: are the workflows that do run succeeding? The foundation is a single global Error Workflow for the instance, referenced in the settings of every production workflow, notifying Slack or email with the workflow name, the failing node and a link to the failed execution. Its setup is detailed in our error-handling guide.

As a complement, the executions list in the n8n interface remains the daily diagnostic tool: filter by "Error" status, spot a workflow failing in a loop, compare execution durations. A quick review every morning is often enough to catch a drift before it becomes an incident.

Prune execution data before it fills up PostgreSQL

Every stored execution weighs on the database — and on an active instance, the executions table can reach several gigabytes within months, degrading performance and then filling the disk (which, back to layer 1, takes the instance down). n8n provides environment variables for automatic pruning:

• EXECUTIONS_DATA_PRUNE=true — enables automatic pruning of old executions.
• EXECUTIONS_DATA_MAX_AGE — the maximum age (in hours) beyond which execution data is deleted; a value of 168 (7 days) to 336 (14 days) suits most instances.

Two nuances: if your workflows carry traceability obligations, don't rely on the n8n execution history as an audit trail — externalize events to a dedicated database, as our Supabase audit-logging workflow does. And pruning is no substitute for backups: the PostgreSQL database holds your workflows and credentials, and deserves the routine described in our PostgreSQL backup and restore guide.

Layer 3: metrics over time

Enabling the Prometheus endpoint

The first two layers detect incidents; metrics reveal trends — execution volume doubling, durations creeping up, the queue swelling. n8n natively exposes a Prometheus-format endpoint: set the N8N_METRICS=true environment variable, restart, and the /metrics endpoint becomes available.

What to look at first:

• Execution counters (succeeded, failed): a rising failure rate is the earliest signal of an external API problem or an expired credential.
• In queue mode with Redis: the queue metrics — waiting jobs piling up signal undersized workers well before users notice the slowness.

A Prometheus scraping this endpoint plus a Grafana dashboard on top is the classic setup. It's optional for a small instance — the uptime probe and the Error Workflow cover the essentials — but it becomes relevant as soon as the instance carries high-volume workflows, or you want to correlate activity with costs, in the spirit of our article on tracking the cost of AI calls.

Logs: the third eye everyone forgets

When an incident happens, metrics tell you that something is wrong; logs often tell you why. In Docker, docker logs -f <container> (or docker compose logs -f n8n) gives access to the stream, and the N8N_LOG_LEVEL variable controls verbosity (info by default, debug to investigate a specific problem). A study published in Communications of the ACM (Oliner, Ganapathi & Xu, 2012, "Advances and Challenges in Log Analysis" — Google Scholar) stresses that logs remain an under-exploited resource even though they are indispensable for diagnosing production systems — an observation that applies perfectly to n8n instances, where the reflex of reading the container logs solves a good share of the mysteries (instance restarting in a loop, refused PostgreSQL connection, saturated memory).

The "meta" workflow: n8n watching itself

The last building block is elegant because it uses n8n to monitor n8n: a minimal heartbeat workflow, fired by a Schedule Trigger every 5 or 10 minutes, sending a simple GET to a service like healthchecks.io. The dead man's switch principle: the service doesn't alert when the signal arrives, but when it stops arriving beyond a grace period.

This setup has a property the /healthz probe doesn't: it verifies the complete, real chain — the instance is online, and the scheduler fires on time, and executions complete, and outbound networking works. An instance can answer 200 on /healthz while its scheduler is stuck or its queue saturated: the heartbeat would catch it. Three precautions:

• Keep this workflow trivial (one Schedule Trigger, one HTTP Request): every added node is a false-positive waiting to happen.
• Set the service's grace period to 2-3 times the heartbeat interval, to tolerate a planned restart.
• Check the Schedule Trigger's timezone, a classic trap covered in our Schedule Trigger guide.

Where to start, concretely

In order of effort-to-benefit ratio:

• Day 1: external uptime probe on /healthz (10 minutes), global Error Workflow (30 minutes), execution pruning (EXECUTIONS_DATA_PRUNE + EXECUTIONS_DATA_MAX_AGE, 5 minutes).
• Week 1: heartbeat workflow to healthchecks.io, executions-list review folded into the routine.
• When volume justifies it: N8N_METRICS=true, Prometheus and Grafana, log centralization.

This gradual approach is one of self-hosting's arguments against managed cloud — you control everything, but nothing is provided for you, a trade-off detailed in our self-hosted vs cloud comparison. And if your workflows carry regulatory obligations, monitoring meets traceability: the Compliance & Audit Pack (€149) includes the audit-logging and journaling workflows that naturally complete the setup described here.