Observability & Telemetry
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts
- packages/cli/src/modules/instance-ai/eval/mock-handler.ts
- packages/nodes-base/AGENTS.md
- packages/nodes-base/TESTING_PROMPT.md
- packages/@n8n/instance-ai/src/knowledge-base/tests/materialize-knowledge-base.test.ts
Observability and Telemetry in n8n provide mechanisms to monitor, analyze, and ensure the health of workflows and the underlying platform. The system encompasses periodic health checks, event-driven monitoring, performance tracking of AI components, and detailed logging of workflow executions.
The system relies on a combination of built-in nodes, error-handling triggers, and evaluation agents to maintain visibility into complex automated processes. Users implement these tools to track service uptime, detect data anomalies, and monitor resource consumption within the n8n environment.
Monitoring Architecture
The monitoring architecture utilizes a scheduled or event-driven approach to verify service status. It relies on specific node configurations to prevent silent failures.
Health Check Flow
The system executes periodic checks using the Schedule Trigger. To ensure visibility during outages, monitoring nodes must use "Continue On Fail" mode. Without this setting, the workflow stops at the failure point, preventing the execution of alert nodes.
The diagram shows the standard monitoring pattern where a trigger initiates a check, followed by conditional logic to route alerts.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts:7-13, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts:114-118
Key Monitoring Components
| Component | Purpose | Behavior |
|---|---|---|
| Schedule Trigger | Periodic Execution | Runs checks at fixed intervals (e.g., every 5 minutes). |
| HTTP Request | Service Verification | Probes endpoints; must have "Continue On Fail" enabled. |
| Error Trigger | Workflow-level Recovery | Executes a dedicated error workflow when the main workflow fails. |
| Execute Command | System Level Check | Runs ping or custom scripts for non-HTTP monitoring. |
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts:51-87, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/monitoring.ts:100-103
Data Analysis and Anomaly Detection
Telemetry data is analyzed using an Input → Transform → Output pattern. This process identifies trends and detects outliers in the data stream.
Processing Pipeline
- Ingestion: Data enters via HTTP, database, or spreadsheet nodes.
- Transformation: The
Setnode cleans fields, while theFilternode removes null values. - Analysis: The
Codenode (formerlyFunction) performs statistical calculations like mean, median, and standard deviation across the whole dataset. - Aggregation: The
Aggregatenode groups items to calculate sums or averages per category.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:7-25, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:80-92
Anomaly Detection Logic
The diagram illustrates the data analysis flow used to identify telemetry anomalies.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:27-39
AI Evaluation and Mocking
The platform includes specialized observability for AI components, specifically through evaluation agents and mock handlers.
LLM-Powered Mock Handler
The EvalLlmMockHandler generates realistic HTTP responses for API mocking during evaluation. It captures detailed metrics such as:
- Request Identifiers: Service name, hostname, and endpoint path.
- Performance Metrics: Generation duration (elapsedMs).
- Errors: Internal LLM errors or tool rejections.
- Time Anchors: Relative date anchors to ensure consistency in time-based filtering.
Sources: packages/cli/src/modules/instance-ai/eval/mock-handler.ts:47-81, packages/cli/src/modules/instance-ai/eval/mock-handler.ts:153-172
Evaluation Feedback Metrics
Telemetry from AI evaluations includes structured feedback on different metrics:
| Metric | Description |
|---|---|
pairwise_primary | Main success score for AI generation comparisons. |
pairwise_diagnostic | Detailed diagnostic score for AI behavior. |
pairwise_judges_passed | Number of judge agents that approved the output. |
Sources: packages/cli/src/modules/instance-ai/eval/mock-handler.ts:316-335
Execution Observability
Execution observability focuses on tracking the state and security of nodes during runtime.
Security and State Logging
Nodes are required to use safe object property helpers to prevent prototype pollution during dynamic data writes. The system monitors these operations to ensure data integrity.
isSafeObjectProperty(table): Validates if a key is safe to write.setSafeObjectProperty(acc, table, {}): Safely sets properties on an accumulator object.
Sources: packages/nodes-base/AGENTS.md:88-100
Diagnostic Testing
The TESTING_PROMPT defines standard patterns for diagnostic observability in unit tests:
// Example of capturing execution result for diagnostics
const result = await node.execute.call(mockExecuteFunctions);
expect(result).toEqual([[
{ json: { id: '123', name: 'Test' }, pairedItem: { item: 0 } }
]]);
Sources: packages/nodes-base/TESTING_PROMPT.md:162-171
Conclusion
Observability and Telemetry in n8n provide the necessary infrastructure to manage high-volume automation with confidence. By combining proactive monitoring with "Continue On Fail" strategies, detailed data analysis pipelines, and specialized AI evaluation tools, the system ensures that both standard and AI-driven workflows remain reliable and transparent. Monitoring the monitoring system itself via Error Triggers and external heartbeats closes the visibility loop, preventing blind spots in mission-critical environments.