Observability & Telemetry
Relevant source files
The following files were used as context for generating this wiki page:
The Observability and Telemetry system provides comprehensive monitoring, performance tracking, and health diagnostics for the n8n application. It encompasses three primary pillars: Metrics (Prometheus), Tracing (OpenTelemetry), and Telemetry (usage tracking). These systems allow administrators and developers to gain insights into workflow execution performance, system resource utilization, and operational health.
This system is integrated into the core CLI and workflow engine, supporting both internal usage statistics and external monitoring integrations. It ensures that critical system events—such as workflow failures, execution durations, and resource exhaustion—are visible and actionable.
Sources: packages/cli/src/modules/otel/otel.service.ts, packages/cli/src/metrics/prometheus/prometheus.service.ts, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts
System Architecture
The observability stack is designed to be decoupled yet comprehensive. The architecture separates the collection of telemetry data from its export to various backends like Prometheus or OpenTelemetry collectors.
Monitoring Data Flow
The following diagram illustrates how performance data and system events flow from the core application to external observability platforms.
The diagram shows the distribution of core engine events to specialized services for metrics, tracing, and telemetry usage tracking.
Sources: packages/cli/src/metrics/prometheus/prometheus.service.ts, packages/cli/src/modules/otel/otel.service.ts
Core Monitoring Components
Prometheus Metrics
The Prometheus service tracks quantitative data about the n8n instance. It exposes an HTTP endpoint (typically /metrics) that external Prometheus scrapers can call to collect time-series data.
| Component | Description |
|---|---|
| Workflow Metrics | Tracks execution counts, success/failure rates, and durations. |
| System Metrics | Monitors Node.js process health, memory usage, and CPU load. |
| Worker Metrics | In queue mode, tracks task throughput and worker availability. |
Sources: packages/cli/src/metrics/prometheus/prometheus.service.ts, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts
OpenTelemetry (OTEL) Tracing
The OpenTelemetry service provides distributed tracing capabilities. This is used to follow a single request or workflow execution across multiple microservices or internal modules, helping to identify latency bottlenecks in complex environments like HA (High Availability) or Multi-Main setups.
This sequence shows the lifecycle of a trace span during workflow execution.
Sources: packages/cli/src/modules/otel/otel.service.ts
Workflow-Level Monitoring Strategies
Monitoring is also implemented at the user-facing workflow level. The system provides specialized nodes and configuration patterns to ensure that automated workflows remain healthy.
Best Practices for Resilience
- Error Trigger Workflows: Configured in settings to alert when a monitoring workflow itself fails, preventing blind spots.
- Heartbeat Pings: Workflows can ping external services (e.g., healthchecks.io) to verify they are running as scheduled.
- Continue On Fail: A critical setting for monitoring nodes (like HTTP Request) to ensure the workflow proceeds to alert actions even if a service check fails.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts:46-52
Recommended Monitoring Nodes
| Node | Purpose | Critical Setting |
|---|---|---|
| Schedule Trigger | Periodic execution of health checks. | Interval (1-60 mins). |
| HTTP Request | Probing website or API availability. | Continue On Fail: true. |
| Wait | Throttling repeated alerts to avoid "alert storms". | Wait Duration. |
| Error Trigger | Global handler for workflow-level failures. | Linked in Workflow Settings. |
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts:63-85
Testing Observability
The project includes specific infrastructure for testing the observability stack during development and CI, utilizing VictoriaMetrics and VictoriaLogs.
VictoriaMetrics Integration
For testing purposes, logs and metrics are automatically attached to test failures in containerized environments. These can be imported locally for analysis.
| Tool | Endpoint | Purpose |
|---|---|---|
| VictoriaMetrics UI | http://localhost:8428/vmui/ | Querying time-series metrics from tests. |
| VictoriaLogs UI | http://localhost:9428/select/vmui/ | Searching through container logs. |
Sources: packages/testing/playwright/README.md:310-318
# Importing exported data into a local Victoria instance
node scripts/import-victoria-data.mjs victoria-metrics-export.jsonl victoria-logs-export.jsonl
Sources: packages/testing/playwright/README.md:314
Summary
The Observability & Telemetry system in n8n provides a multi-layered approach to system visibility. By combining lower-level instrumentation (Prometheus/OTEL) with high-level workflow monitoring patterns (Error Triggers/Continue On Fail), it ensures that both infrastructure-level health and business-logic accuracy are maintained. This robustness is further supported by an integrated testing pipeline that captures observability data during failures to facilitate rapid debugging.