Trace executions with OpenTelemetry

n8n can emit OpenTelemetry traces for workflow and node executions. Use these traces to monitor execution latency, debug failures, and track requests across services in your observability stack.

Watch an overview of OpenTelemetry tracing in n8n:

What you get

When you turn on tracing, n8n exports two kinds of spans for each execution:

• workflow.execute: One span per workflow execution. It records the workflow ID, name, version, node count, execution mode, status, and any error type.
• node.execute: One span per node execution, nested inside its workflow span. It records the node ID, name, type, version, and the number of input and output items.

Each span includes resource attributes that identify the n8n instance:

• service.name (default n8n)
• service.version (the n8n version)
• n8n.instance.id
• n8n.instance.role (for example, main, worker, or webhook)

n8n also handles trace context propagation:

• Inbound: If a webhook request includes a W3C traceparent header, n8n uses it as the parent for the workflow span. This links the n8n workflow trace to the upstream caller.
• Outbound: HTTP Request nodes (and other nodes that use the n8n HTTP helpers) can inject a traceparent header into outbound requests. Downstream services that support W3C trace context can therefore continue the trace.
• Sub-workflows: A sub-workflow's span uses the parent workflow's span as its parent.
• Resumed workflows: When a workflow resumes after a wait, the new span links back to the previous span using a span link.

Enable tracing in the UI

Instead of setting environment variables, you can configure tracing from Settings > OpenTelemetry. n8n applies your changes without a restart, and reloads them across workers and webhook processors in queue mode.

To configure tracing:

1. Select Settings > OpenTelemetry.
2. Turn on Enable OpenTelemetry.
3. Under Collector connection, enter your OTLP endpoint and any other connection details.
4. Under Tracing, set your sampling and span options.
5. Select Save settings.

To check that n8n can reach your collector, select Send test trace under Verify configuration. n8n sends a single test span and reports whether the collector accepted it. You can run this before or after you save.

Each field maps to an environment variable, shown in the field's tooltip. For the full list, see OpenTelemetry environment variables.

Enable tracing with environment variables

Set the following environment variables on each n8n instance you want workflow tracing enabled (main, workers, and webhook processors):

export N8N_OTEL_ENABLED=true
export N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://<your-collector-host>:4318

Restart n8n. The instance starts exporting spans over OTLP HTTP using the Protobuf encoding.

n8n appends /v1/traces to the endpoint by default. Point N8N_OTEL_EXPORTER_OTLP_ENDPOINT at the base URL of your collector, not the traces path.

If your collector needs authentication, set N8N_OTEL_EXPORTER_OTLP_HEADERS to a comma-separated list of key=value pairs:

export N8N_OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <your-token>,x-tenant=acme"

// For added protection - It is recommended to use the `_FILE` postfix if you are putting a token in here:
export N8N_OTEL_EXPORTER_OTLP_HEADERS_FILE=/mnt/otel-headers

For the full list of supported variables, refer to OpenTelemetry environment variables.

Sampling

By default, n8n exports every trace. To reduce volume in busy instances, set N8N_OTEL_TRACES_SAMPLE_RATE to a value between 0 and 1:

# Export 10% of traces
export N8N_OTEL_TRACES_SAMPLE_RATE=0.1

n8n uses a trace ID ratio sampler, so the same trace ID is either fully sampled or fully dropped across all spans in the trace.

Reduce span volume

Each node in a workflow produces its own span. For workflows with lots of nodes, this can produce more data than you need. To export only workflow-level spans, set:

export N8N_OTEL_TRACES_INCLUDE_NODE_SPANS=false

To stop n8n from injecting traceparent headers into outbound HTTP requests, set:

export N8N_OTEL_TRACES_INJECT_OUTBOUND=false

Agent tracing

n8n can also emit spans for AI agent runs, using the same tracer as workflow tracing. This covers agent runs started from a workflow (for example, the AI Agent node), from chat integrations, and from scheduled tasks.

Agent tracing rides along with the rest of the OTel module. With N8N_OTEL_ENABLED turned on, add:

export N8N_AGENTS_TRACING_ENABLED=true

Set it to false to keep workflow and node spans while dropping agent spans.

By default, agent tracing records prompts, tool arguments, responses, and tool results. To exclude sensitive input or output data:

export N8N_AGENTS_TRACING_RECORD_INPUTS=false
export N8N_AGENTS_TRACING_RECORD_OUTPUTS=false

For the full list of variables, refer to OpenTelemetry environment variables.

What you get

Each agent run produces one root span, named <agent name>.generate or <agent name>.stream depending on whether the run streams its response. Each tool call the agent makes produces a nested execute_tool <tool name> span.

These spans use the OpenTelemetry GenAI semantic conventions (gen_ai.* attributes), so they're readable in any OTLP backend, not just tools built for LangSmith.

Custom span attributes

You can add custom attributes to project, workflow, and node spans. n8n exports each custom attribute as an OpenTelemetry span attribute to your configured observability backend.

Don't include secrets, personal data, or other sensitive values in attribute values.

n8n supports the following custom attribute levels:

Project and workflow custom span attributes are available from n8n 2.24.0. Node custom span attributes are available from n8n 2.22.0.

Add project span attributes

To add project-level span attributes:

1. Open a project.
2. Select Project settings.
3. Under Custom Span Attributes, add one or more span attributes.
4. Select Save.

Use plain text for project attribute values.

Add workflow span attributes

To add workflow-level span attributes:

1. Open the workflow.
2. Open Workflow settings.
3. Under Custom Span Attributes, select Configure.
4. Add one or more span attributes.
5. Select Save.

Use plain text for workflow attribute values.

Add node span attributes

To add node-level span attributes:

1. Open the node and select the Settings tab.
2. Under Custom Span Attributes, select Add Attribute.
3. Enter a Key. Keys must be plain text.
4. Enter a Value. Values can be plain text or expressions, such as ={{ $json.environment }}.

Node attribute values must resolve to a string, number, or boolean.

Add attributes programmatically in a custom node

If you're building a custom node, you can attach custom key-value pairs from code. Call setMetadata from the node's execute method:

async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
	this.setMetadata({
		tracing: {
			'llm.model': 'gpt-4o',
			'llm.token.input': 1500,
			'llm.token.output': 340,
		},
	});

	return [this.getInputData()];
}

n8n prefixes each key with n8n.node.custom. on the exported span. Values must be strings, numbers, or boolean.

This API isn't available from the Code node. It's intended for node authors who want to enrich spans with domain-specific data.

If a node sets an attribute key here that's also configured as a custom node span attribute, the programmatic value takes precedence.

Try it out with Jaeger

You can send traces to a local Jaeger instance to see them in action.

1. Save the following as docker-compose.yml:

services:
  jaeger:
    image: jaegertracing/jaeger:latest
    ports:
      - "16686:16686" # UI
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP

1. Start Jaeger:

docker compose up -d

1. Start n8n with tracing turned on and pointed at Jaeger. Refer to starting n8n for setup details:

N8N_OTEL_ENABLED=true N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 n8n start

1. Run a workflow, then open the Jaeger UI at <http://localhost:16686> - Select "n8n" as service" and click "Find traces" to see the OpenTelemetry traces emitted by n8n.

Span attributes

Workflow and node spans include the following n8n-specific attributes.

Workflow span (workflow.execute)

Node span (node.execute)

When a node fails, n8n records an exception event on the span with the standard OpenTelemetry exception attributes (exception.type, exception.message, exception.stacktrace).

Agent run span (<agent name>.generate or <agent name>.stream)

Tool call span (execute_tool <tool name>)

Troubleshooting

No traces appear in your backend

If n8n can't reach the OTLP endpoint at startup, it logs an error:

Failed to connect to OpenTelemetry OTLP endpoint during startup

Check that:

• N8N_OTEL_ENABLED is set to true.
• N8N_OTEL_EXPORTER_OTLP_ENDPOINT points at the base URL of the collector (not the /v1/traces path).
• The collector is reachable from the n8n container or host.
• Any required N8N_OTEL_EXPORTER_OTLP_HEADERS (such as authentication tokens) are set.

n8n logs OpenTelemetry diagnostics at warn level by default. Set N8N_LOG_LEVEL=debug to see more detail.

Custom span attributes are missing

Check that:

• You have an Enterprise license.
• You set N8N_OTEL_ENABLED to true.
• For node-level span attributes, N8N_OTEL_TRACES_INCLUDE_NODE_SPANS isn't set to false.

Worker traces are missing parent context

In queue mode, workers read the parent trace context from the database. If you only set the OpenTelemetry environment variables on the main instance, worker spans won't link to the parent workflow trace. Set the same variables on every instance type.

No agent spans appear

Agent spans depend on the OTel module. Check that:

• N8N_OTEL_ENABLED is set to true.
• N8N_AGENTS_TRACING_ENABLED is set to true.

With N8N_OTEL_ENABLED set to false, agent runs complete normally, but n8n emits no spans for them, even with N8N_AGENTS_TRACING_ENABLED set to true.

Related resources

• OpenTelemetry environment variables
• W3C Trace Context specification
• OpenTelemetry Collector documentation
• Logging in n8n
• Monitoring