> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://respan.ai/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server. # n8n > Trace n8n's native OpenTelemetry spans or call Respan Gateway from an n8n workflow. [n8n](https://n8n.io/) is a workflow automation platform with native OpenTelemetry execution tracing and general-purpose HTTP workflow nodes. Respan supports two separate integration paths: * **Tracing** translates n8n's native workflow, node, Agent, LLM, tool, and memory spans with `@respan/instrumentation-n8n`. * **Gateway** calls Respan's OpenAI-compatible Chat Completions route from an n8n workflow. #### Set up Respan Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys). For Gateway calls, also add [credits](https://platform.respan.ai/platform/gateway/credits) or configure a [provider key](https://platform.respan.ai/platform/gateway/api-keys?providers=1). Run `npx @respan/cli setup` to set up with your coding agent. #### Source, examples, and Gateway guide * [Instrumentation source and package README](https://github.com/RespanAI/respan/tree/main/javascript-sdks/instrumentations/respan-instrumentation-n8n) * [n8n native OpenTelemetry examples](https://github.com/RespanAI/respan-example-projects/tree/main/typescript/tracing/n8n) * [Respan Gateway API](/docs/integrations/gateway/respan-api) * [n8n Gateway setup](/docs/integrations/gateway/n-8-n) #### Tracing ## How tracing works `@respan/instrumentation-n8n` preloads before n8n constructs its OpenTelemetry `NodeSDK`. It keeps n8n's provider and OTLP/HTTP Protobuf exporter as the sole tracing pipeline; it does not create a second provider and does not require a Respan node inside each workflow. ## Confirmed compatibility | Surface | Confirmed n8n versions | | --------------------------------------------------------------- | ------------------------- | | Native `workflow.execute` and `node.execute` spans | `2.19.0` through `2.37.7` | | Current Agents, inner AI SDK LLM calls, tools, and memory spans | `2.33.0` through `2.37.7` | 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 #### Install n8n and the instrumentation together ```bash npm install n8n@2.37.7 @respan/instrumentation-n8n@0.1.0 ``` Install both packages in the same Node.js project and process so n8n can resolve the preload entrypoint. #### Configure Respan and n8n's native exporter ```bash 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 ``` `NODE_OPTIONS` must be set before n8n starts. The preload activates `N8nInstrumentor` before n8n imports `@opentelemetry/sdk-node`. #### Start n8n ```bash npx n8n start ``` `N8N_OTEL_TRACES_PRODUCTION_ONLY` defaults to `true`. To inspect a local manual execution during a deliberate audit, set it to `false` before starting n8n: ```bash export N8N_OTEL_TRACES_PRODUCTION_ONLY=false ``` Production deployments should normally keep the default. #### Inspect the trace Open the [Traces page](https://platform.respan.ai/platform/traces). Search by workflow name or a run-specific marker, then inspect the complete tree and individual span content rather than relying on trace presence alone. ## 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 | Native span | Respan type and semantic name | Confirmed behavior | | ------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workflow.execute` | `workflow` → `workflow` | Workflow ID, name, version, node count, execution ID/mode/retry/final status, project data, and failure details are promoted. | | `node.execute` | `task` → `task` | Node ID/name/type/version, input/output item counts, termination reason, status, and failure details are promoted. Workflow parentage is preserved. | | `.generate` / `.stream` | `agent` → `agent.` | Agent identity, thread correlation, tool-catalog input, and Agent metadata are normalized. | | `ai.generateText.doGenerate` / `ai.streamText.doStream` | `text` → `llm.` or bare `llm` | Prompt/completion messages, tools, current-turn tool calls, model/provider, input/output/total/cache token usage, response metadata, and stream timing are normalized. | | `execute_tool ` | `tool` → `tool.` | Tool name, call ID, arguments, result, status, and LLM parentage are retained without redundant tool-call aliases. | | `query_memory` / `save_memory` | `task` → `task` | Memory input/output plus IDs, owners, types, operations, descriptions, and store details are retained under entity content and `respan.metadata.n8n.memory`. | 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: ```bash 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: ```bash 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. #### Gateway ## Call Respan Gateway from n8n Respan Gateway can serve an LLM request made by an n8n workflow. n8n is the caller/orchestrator in this path; it is not an upstream model provider, and Respan Gateway does not execute the workflow itself. Use the dedicated [n8n Gateway setup](/docs/integrations/gateway/n-8-n) for the current HTTP Request configuration, managed-prompt schema v2 body, credential guidance, and safe migration steps for workflows that still reference the archived community node. Gateway requests are logged independently from native n8n OpenTelemetry traces. Enable the Tracing tab's instrumentation when you also need the surrounding workflow, node, Agent, tool, and memory tree; do not assume the two records are linked unless end-to-end trace-context correlation has been implemented and verified.