n8n-nodes-observability

OpenTelemetry tracing for n8n AI Agent workflows.

The AI Trace Exporter is a passthrough sub-node between a Chat Model and an
AI Agent. It exports OTLP/HTTP JSON to Comet Opik, Langfuse, or a generic
OpenTelemetry collector. Datadog is supported through an OpenTelemetry
Collector. The package has no runtime dependencies and does not modify the
model or agent nodes.

flowchart LR
    model["Chat Model"] -->|"Chat Model"| exporter["AI Trace Exporter"]
    exporter -->|"Traced Chat Model"| agent["AI Agent"]

The exporter sits between the Chat Model and AI Agent and turns green when the model runs.

Trace structure

Each agent invocation gets a synthetic root span, one child span per model
call, and reconstructed tool spans:

flowchart TD
    trace["support-agent-run<br/>execution totals"]
    first["chat claude-sonnet-4-6<br/>tokens, latency, TTFC"]
    tool["execute_tool calculator<br/>inferred timing"]
    final["chat claude-sonnet-4-6<br/>tokens, finish reason"]
    trace --> first
    trace --> tool
    trace --> final

One agent invocation in Opik: two model calls and the reconstructed Calculator call in one trace.

The root carries call, tool, and error counts plus input, output, cache-read,
cache-creation, and reasoning-token totals when the provider reports them.
Model spans include normalized provider/model names, request controls,
response metadata, token details, latency, streaming state, and time to first
chunk. Backends can derive per-call cost from the model and token attributes;
the node does not maintain a pricing table.

Installation

On self-hosted n8n, open Settings → Community Nodes → Install and enter
n8n-nodes-observability.

The node requires n8n's AI nodes and Node.js 22.22 or newer. It sends data only
to the OTLP endpoint configured in its credential.

Setup

1. Connect a Chat Model to the AI Trace Exporter, then connect the
   exporter's output to an AI Agent.
2. Create an OTLP Trace Exporter API credential.

Additional Headers are applied after the preset and primary auth. This
supports authenticated proxies and allows an explicit header to override a
preset value.

The credential's Test button POSTs an empty OTLP payload
({"resourceSpans":[]}) to <endpoint>/v1/traces. The request checks the same
URL and authentication used by the exporter without ingesting a span.

3. Set Trace Name if needed. Session ID, User ID, and Metadata
   are expression-friendly.

Session ID is exported as gen_ai.conversation.id, thread_id, session.id,
and langfuse.session.id. User ID is exported as user.id and
langfuse.user.id. Use a stable chat session key such as
{{ $json.sessionId }} to group related executions.

Options

Structured redaction paths

Version 3 accepts a small field-path language, not full JSONPath. A rule is
applied only when the captured value is valid JSON.

Invalid or unsafe regexes and invalid field paths are ignored and reported by
count; their contents are not logged. Serialization is bounded by depth, item
count, string size, and the configured captured-content limit. Circular or
hostile objects cannot block the workflow.

If n8n's execution redaction policy blocks content, that policy is a hard
ceiling: prompt/response and tool I/O capture stay disabled even when enabled
on the node. Capture also stays disabled if the runtime cannot expose its
redaction policy. The execution receives a warning explaining why.

Delivery behavior

Export is best-effort and never fails the workflow. Spans are coalesced and
bounded by both count and serialized size:

• Each exporter retains at most 200 spans or 2 MiB and sends at most 64 spans
  or 512 KiB per request. Oldest queued spans are dropped when a bound is
  reached.
• The synthetic agent root is sent in its own request. A duplicate-root
  conflict cannot reject newly queued child spans in the same batch.
• Across one n8n worker process, at most four OTLP requests run concurrently;
  the shared pending-request queue is also bounded.
• Recognized transient network failures and HTTP 429, 502, 503, and
  504 are retried up to three total attempts with capped exponential backoff and jitter.
  Retry-After is honored, capped at 30 seconds. Other HTTP failures are not
  retried.
• OTLP partial-success responses are recorded as partial acceptance, including
  rejected-span counts. Collector and proxy error text is not retained or
  logged because it can echo captured payload content.
• When the tracing pipeline finalizes, the node performs a 250 ms best-effort
  flush. A
  timeout, rejection, partial acceptance, or queue overflow is surfaced as an
  n8n execution warning; it is not thrown into the workflow.

The execution-state output reports exportStatus: queued, not delivered,
because delivery remains asynchronous. A sampled run includes traceId and
rootSpanId; an unsampled run reports exportStatus: notSampled and exposes
no correlation IDs. Captured prompt, response, and tool content is never copied
into the n8n execution-state output.

Invocation boundaries and native correlation

The tracing registry isolates executions by n8n execution ID, Trace Exporter
node ID, parent run index, and item index. Steppable AI Agent calls reuse the
same trace across model/tool steps, while parallel fan-out on the same boundary
gets separate pipeline slots. Terminal answers, errors, and cancellation close
the trace; an abandoned tool tail is finalized after a bounded quiet period.

When the active n8n runtime exposes native tracing metadata, the node adds
ai_observability_trace_id and ai_observability_root_span_id without
overwriting existing string, number, or boolean metadata. This provides
queryable correlation, not OpenTelemetry parentage. n8n's public
community-node API does not expose the active native span context, so the
exported synthetic root cannot currently be made a child of n8n's own
execution span.

Tool span limitation

Actual Calculator, HTTP, and other tool executions occur outside a
model-attached callback. The node reconstructs execute_tool <name> spans from
the model's requested calls and the results returned in the next model input,
including n8n V3's Calling <tool> with input: <JSON> fallback. Reconstructed
spans carry:

• n8n.span.synthesized: true
• n8n.span.timing_source: inferred
• n8n.tool.result_observed: false when no later model call contains a result

Their duration spans the surrounding model-call boundaries and may include n8n
framework overhead. Exact tool runtime, failures before a result reaches the
model, and exact tool cancellation state require an n8n-core lifecycle hook. Tool
arguments and results are exported only when Include Tool Inputs and
Outputs is enabled.

Compatibility

CI builds and runs contract tests against n8n-workflow 2.27, 2.28, and 2.29
on the minimum supported Node.js version, 22.22. The tracer attaches through
LangChain callbacks and normalizes provider payload differences rather than
depending on one model vendor.

Roadmap

• Engine-level tool lifecycle spans with exact timing
• A stable evaluation-score/feedback and dataset-item write contract
• Gzip compression and raw-byte OTLP transport
• Multiple export destinations from one trace

License

MIT