Ctrlk
HomeLog InSign UpSend Feedback
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Trace n8n Workflow Executions with the Tracing Service

Overview

This tutorial demonstrates how to export execution traces from n8n into the IONOS CLOUD Tracing Service (powered by Grafana Tempo). Using n8n's built-in OpenTelemetry support, you will send workflow and node execution spans to a tracing pipeline through the standard OpenTelemetry Protocol (OTLP), without changing any workflow logic or writing code. You will then explore the traces in Grafana to see how long each node takes and where a workflow spends its time.

This tutorial covers n8n workflow and node execution tracing. n8n also offers a separate AI agent tracing feature; to trace AI agents and LLM calls with gen_ai.* span attributes, see Trace an AI Agent That Uses AI Model Hub with the Tracing Service.

Target audience

This tutorial benefits DevOps engineers, platform teams, and automation developers who run n8n and want centralized visibility into workflow performance and failures. Readers benefit from basic familiarity with:

  • Running containers with Docker

  • Environment-variable configuration

  • The IONOS CLOUD Console and API authentication

  • Grafana and trace exploration concepts

What you will learn

  • How to create a IONOS CLOUD tracing pipeline and retrieve its ingestion endpoint and key.

  • How to activate n8n's built-in OpenTelemetry export using the settings UI or environment variables.

  • How to point n8n at your tracing pipeline over OTLP/HTTP.

  • How to run a workflow and view its trace in Grafana.

  • How to query traces with TraceQL and troubleshoot common ingestion problems.

Before you begin

Ensure you have:

  • An active IONOS CLOUD account with the Access and manage Tracing privilege.

  • An IONOS CLOUD API token to create the pipeline. To generate a token, see Token Manager.

  • Docker installed on a host with outbound HTTPS access on port 443.

  • Basic familiarity with the Tracing Service documentation.

Cost considerations

This tutorial creates a billable IONOS CLOUD tracing pipeline. Charges are based on the volume of trace data ingested and stored. There is no base fee and no minimum commitment.

Delete the pipeline after you finish to avoid ongoing charges. For current rates, see the IONOS CLOUD price list (EUR).

Architecture

The diagram below shows the data flow from n8n to Grafana:

Architecture: n8n exports workflow and node spans over OTLP/HTTP to the IONOS Tracing pipeline, which ingests and stores them in the Tracing Service (Grafana Tempo) for querying in Grafana.

n8n's OpenTelemetry module creates a span for each workflow execution and a child span for each node. It exports them over OTLP/HTTP to your tracing pipeline, where they are stored in Tempo and become searchable in Grafana.

Procedure

1

Create a tracing pipeline.

Create a pipeline configured for the otlp-http protocol. Send a POST request to the regional Tracing Service API endpoint, replacing the region host as needed:

The create response returns the pipeline id and the ingestion key (key). Save the key immediately: it is returned only once, on creation.

Warning: Save the key immediately. The Tracing Service returns the ingestion key only once. Store it securely, such as in a password manager. If you lose it, rotate the pipeline key through the Tracing Service API to generate a new one.

The create response does not include the ingestion endpoint. Retrieve the ingestion endpoint and the grafanaEndpoint with a follow-up GET request, using the pipeline id from the previous response:

From this response, save:

  • The ingestion endpoint (the otlp-http traces endpoint, of the form https://<tracing-host>/v1/traces).

  • The grafanaEndpoint, the Grafana instance address for exploring traces.

For more information on pipelines, endpoints, and regions, see Tracing Pipelines.

2

Activate OpenTelemetry export in n8n.

You can point n8n at your tracing pipeline in two ways. Use Option A if you configure n8n through its settings UI, or Option B for headless and containerized deployments. Both send the same workflow and node spans.

Option A: Configure in the n8n UI

In n8n, open the OpenTelemetry settings and configure the collector connection, then set Status to Enabled:

The n8n OpenTelemetry settings page, showing Status set to Enabled, the OTLP endpoint and API key custom header for the tracing pipeline, the trace path set to /v1/traces, and node spans enabled.

Set the fields as follows:

  • OTLP endpoint: the base host of your pipeline, https://<tracing-host>. Do not include /v1/traces here; that is set separately in Trace path.

  • Custom headers: add a header with key apikey and the pipeline ingestion key as its value.

  • Trace path: /v1/traces (the OTLP default).

  • Include node spans: activate this to get one span per node in addition to the workflow-level span.

  • Track published workflows only: leave this off while testing so manual (editor) executions are also traced. Activate it to trace only production executions.

Use Send test trace to confirm n8n can reach your pipeline before running a workflow.

Option B: Configure with environment variables

Start n8n with the OpenTelemetry environment variables set. Replace <tracing-host> and <API_KEY> with the ingestion endpoint host and key from the previous step.

The variables do the following:

  • N8N_OTEL_ENABLED=true: turns on n8n's OpenTelemetry module.

  • N8N_OTEL_TRACES_PRODUCTION_ONLY=false: also traces manual (editor) executions, so you can test without activating the workflow. Set to true to trace only production executions.

  • N8N_OTEL_EXPORTER_OTLP_ENDPOINT: the base host of your tracing pipeline, without the /v1/traces path.

  • N8N_OTEL_EXPORTER_OTLP_TRACING_PATH: the traces path appended to the endpoint (/v1/traces).

  • N8N_OTEL_EXPORTER_OTLP_HEADERS: passes the pipeline key as the apikey header for authentication.

Note: Set the endpoint and path separately. In both the UI and the environment variables, the endpoint is the base host (https://<tracing-host>) and /v1/traces is set separately (the UI Trace path field, or N8N_OTEL_EXPORTER_OTLP_TRACING_PATH). Do not append /v1/traces to the endpoint, or n8n appends it twice.

Note: Environment variables must be passed to docker run. A shell export on the host is not inherited by docker run; you must forward each value with -e. Verify the values are set with docker exec n8n env | grep N8N_OTEL.

3

Build and run a workflow.

Open the n8n editor at http://localhost:5678 and create a workflow, for example a Manual Trigger node connected to an HTTP Request node (or any two nodes). Run it with the Test workflow button (manual execution), or activate the workflow and trigger it through its production URL.

The workflow completes without errors. n8n emits one span for the workflow execution and one child span for each node that ran.

4

View traces in Grafana.

Open Grafana using the grafanaEndpoint you retrieved. For more information, see Access Traces from the Platform. Open Explore and select the Tracing (Tempo) data source, which is provisioned automatically for your contract and region.

Search for your traces using the search builder, or run a TraceQL query. n8n names the workflow span workflow.execute and each node span node.execute, so you can query the workflow span directly:

To list every span from this n8n instance regardless of type, filter by the service name you configured (the default is n8n):

Open a workflow.execute trace to see its node.execute child spans nested underneath, each showing its duration. Click a node span to inspect its attributes, such as n8n.node.name, n8n.node.type, and n8n.node.items.input/n8n.node.items.output.

A Grafana Tempo view of an n8n trace: a parent workflow span with a child node span, and a span-attributes panel showing n8n.node.id, n8n.node.name, n8n.node.type, and n8n.node.items.input and output.

Info: Node names and types reflect your workflow. The n8n.node.name and n8n.node.type values in the trace come from the nodes in your own workflow, so your spans will differ from this example.

Result: Your n8n workflow executions now appear as traces in Grafana, with each node.execute span nested under its workflow.execute trace, showing per-node durations and attributes.

Troubleshooting

  1. No traces appear: Confirm the pipeline is in AVAILABLE state and that N8N_OTEL_EXPORTER_OTLP_ENDPOINT and N8N_OTEL_EXPORTER_OTLP_HEADERS are set in the running n8n instance (docker exec n8n env).

  2. Authentication errors (401): Verify the apikey value matches the current pipeline key. Rotate the key through the API if unsure.

  3. Connection errors: Verify outbound HTTPS access on port 443 from the n8n host.

  4. Only production traces appear: Set N8N_OTEL_TRACES_PRODUCTION_ONLY=false to include manual (editor) executions, and restart n8n. Environment changes require a restart.

  5. Endpoint path: Set N8N_OTEL_EXPORTER_OTLP_ENDPOINT to the base host only and put /v1/traces in N8N_OTEL_EXPORTER_OTLP_TRACING_PATH (or the UI Trace path). Including /v1/traces in the endpoint makes n8n append it twice.

Decommission resources

Delete the tracing pipeline through the API to stop billing, using the pipeline id from the creation response:

Then stop n8n (docker stop n8n).

Next steps

PreviousTracing Service
NextTrace an AI Agent that Uses AI Model Hub with the Tracing Service

Last updated

Was this helpful?