n8n

Paste this into your coding agent:

Help me set up Respan tracing with the n8n integration.
Follow https://www.respan.ai/docs/integrations/n-8-n.md

Confirmed compatibility

n8n 2.37.7 is the newest tested target. Its confirmed stack uses @opentelemetry/sdk-node 0.221.0, @n8n/agents 0.22.2, and @ai-sdk/otel 1.0.87. Use Node.js 24 LTS; validation used Node.js 24.19.0.

The instrumentation peer range is >=2.19.0 <2.38.0. n8n versions after 2.37.7, n8n 3.x, and OpenTelemetry SDK versions outside >=0.213.0 <0.222.0 require revalidation. n8n marks native OpenTelemetry tracing as Preview, so emitted shapes and provider construction can change between releases.

Install

npm install n8n@2.37.7 @respan/instrumentation-n8n@0.1.0

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

export NODE_OPTIONS="--import=@respan/instrumentation-n8n/register"
export N8N_OTEL_ENABLED=true
export N8N_OTEL_EXPORTER_OTLP_ENDPOINT="https://api.respan.ai/api"
export N8N_OTEL_EXPORTER_OTLP_TRACING_PATH="/v2/traces"
export N8N_OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${RESPAN_API_KEY}"

export N8N_OTEL_TRACES_INCLUDE_NODE_SPANS=true
export N8N_AGENTS_TRACING_ENABLED=true

npx n8n start

export N8N_OTEL_TRACES_PRODUCTION_ONLY=false

Activation and shutdown

The recommended --import=@respan/instrumentation-n8n/register entrypoint activates one process-wide, reference-counted N8nInstrumentor. Repeated activation is idempotent. The hook modifies only NodeSDK construction whose resource contains both n8n.instance.id and n8n.instance.role; unrelated OpenTelemetry SDK instances are left alone.

n8n owns the provider, batch processor, exporter, flush, and shutdown lifecycle. Stop n8n normally with its process manager, SIGTERM, or Ctrl+C; n8n’s native shutdown flushes the OTLP exporter. N8nInstrumentor.deactivate() only removes the constructor hook for future SDK instances. It does not flush or stop an existing provider and is not a substitute for n8n shutdown. Restart n8n after adding or removing the preload.

If you activate N8nInstrumentor programmatically, call activate() before any n8n code can load @opentelemetry/sdk-node. After n8n completes its own shutdown, call deactivate() to remove the hook for future provider construction.

In queue mode, install and preload the instrumentation and apply the same N8N_OTEL_* configuration to main, worker, and webhook processes. This preserves n8n’s native cross-process propagation.

What gets traced

Current n8n Agents use @ai-sdk/otel’s LegacyOpenTelemetry. Its outer ai.generateText or ai.streamText span is structural when a detailed provider span appears. Semantic export drops that wrapper and reparents the LLM span to the Agent. The AI SDK can also emit ai.toolCall around n8n’s authoritative execute_tool; the duplicate wrapper is suppressed only when its matching n8n tool owner appears. An unmatched AI SDK tool span remains visible as a canonical tool span.

Successful spans receive backend status_code=200 when no more specific status exists. Failed spans retain OpenTelemetry ERROR status, use status_code=500 when no provider or HTTP status is available, and keep exception events. When an ERROR span has standard exception.message data and no error.message, the exporter promotes it to canonical error.message for log detail.

The instrumentation does not set traceloop.span.kind on automatically emitted spans.

Content and privacy

The instrumentation does not read n8n execution records or reconstruct workflow payloads. It can only translate attributes already present on native spans. Workflow and node tracing exposes execution and item-count metadata, not arbitrary per-node payloads.

n8n Agent tracing records prompts, tool arguments, responses, and tool results by default. Suppress recorded model and tool content at the n8n source when required:

export N8N_AGENTS_TRACING_RECORD_INPUTS=false
export N8N_AGENTS_TRACING_RECORD_OUTPUTS=false

When content is absent, the instrumentation does not synthesize it. These flags are not a complete Agent-data off switch in n8n 2.37.7: the Agent root tool catalog and memory correlation fields such as owners, IDs, types, and stores may still be emitted. For strict suppression of Agent content and correlation metadata, disable Agent tracing entirely:

export N8N_AGENTS_TRACING_ENABLED=false

Before export, raw n8n.*, gen_ai.memory.*, and AI SDK ai.* attributes are removed after canonical promotion. Request headers such as ai.request.headers.authorization are never copied into Respan metadata. Arbitrary non-sensitive ai.telemetry.metadata.* values are retained under respan.metadata.n8n.telemetry; secret-shaped keys receive [REDACTED]. Raw AI SDK stream events are removed after timing diagnostics are promoted. Standard exception events, links, timestamps, resource attributes, and canonical parent context are preserved.

If normal translation fails, workflow execution is unaffected. The export fallback removes raw Agent ai.* attributes and events before delegation; if even that cleanup fails for one malformed span, only that span is dropped.

Limitations

• Activate the hook before n8n loads its OpenTelemetry SDK. Late activation cannot retrofit an existing provider.
• If n8n supplies an unknown custom span-processor layout, the adapter leaves it unchanged rather than installing a second provider.
• Deactivation affects future provider construction only. Restart n8n after changing the preload.
• The compatibility statement stops at n8n 2.37.7; do not assume later n8n or OpenTelemetry versions emit the same shapes.
• Prefer environment variables on every queue-mode process so endpoint and header settings cannot drift between roles.

Migrating from the community node

Earlier tracing guidance installed @respan/n8n-nodes-respan, created a Respan credential in the n8n UI, and placed a Respan node into workflows. That package is a Gateway and prompt-management community node, not a trace exporter and not the native OpenTelemetry adapter documented in this tab.

For standard tracing, preload @respan/instrumentation-n8n and configure n8n’s native N8N_OTEL_* exporter. Installing the instrumentation does not replace the community node type or its saved UI credential. Before uninstalling the archived package, inventory every workflow that references its Respan node, convert its Gateway and prompt operations, verify downstream response/error expressions, and confirm that no workflow still depends on the old node. Keep a future maintained Gateway community node when its workflow operations are still needed; Gateway calls and native tracing can coexist.