Ratel Docs
Telemetry

Send n8n traces

Export n8n workflow, AI Agent and model spans to Ratel Cloud with n8n's built-in OpenTelemetry tracing.

See every n8n execution in Ratel Cloud: which workflow ran, how long each node took, and what each AI Agent spent on its model calls.

n8n has built-in OpenTelemetry tracing. You point it at Ratel Cloud. No community node, no collector and no code change.

What you get

What arrives depends on your n8n version. On n8n Cloud, the Overview page of the Cloud console shows it.

n8n versionSpansRatel Cloud shows
2.19 or laterworkflow.execute, node.executeEach execution as a trace: nodes, timing, status, errors
2.46 or laterAI Agent node and chat model spans with gen_ai.*Model calls: provider, model, input and output tokens, cost
3.2.2 or later (beta track)Tool sub-node spans with gen_ai.tool.nameThe tools an AI Agent called

Before n8n 2.46, the AI Agent node sends a plain node span only. It carries no model, no tokens and no tool calls. Update n8n to get model calls in Ratel: see Limits.

n8n labels OpenTelemetry tracing as Preview. Its spans can change between n8n releases.

Before you start

  • A Ratel Cloud project API key (rtl_...). Create one in your project's Settings > API keys on cloud.ratel.sh.
  • An n8n account with the owner or admin role. Members cannot see Settings > OpenTelemetry.
  • n8n 2.27 or later, for the settings page. Self-hosted instances can use environment variables from 2.19.
n8n fieldValue
ProtocolHTTP (protobuf). Ratel does not accept gRPC.
OTLP endpointhttps://cloud.ratel.sh
Trace path/v1/traces
HeaderAuthorization = Bearer <your-ratel-key>

n8n adds the trace path to the endpoint. Do not put /v1/traces in the endpoint too.

n8n Cloud

Do these steps as the instance owner or an admin.

  1. Open your n8n instance. Go to Settings > OpenTelemetry.
  2. Leave Enable OpenTelemetry off for now.
  3. Under Collector connection, set:
    • Protocol: HTTP (protobuf).
    • OTLP endpoint: https://cloud.ratel.sh.
    • Trace path: /v1/traces.
    • Custom headers: add the key Authorization with the value Bearer <your-ratel-key>.
  4. Under Verify configuration, click Send test trace. n8n sends one test span. Expect a success message.
  5. Under Tracing, set the options for a first test:
    • Trace sample rate: 1.00.
    • Include node spans: on.
    • Track published workflows only: off, so manual runs are traced too.
  6. Click Save settings. Then turn on tracing (Enable OpenTelemetry, or Status > Enable on older versions).
  7. Run a workflow. For a full check, run one with an AI Agent node.

n8n starts the export at once. You do not need a restart. Field labels can differ a little between n8n versions.

Tracing covers the whole instance

n8n exports every traced execution of every workflow on the instance. There is no allowlist per workflow. Before you enable tracing on a production instance:

  • Agree the test window with your team.
  • Lower Trace sample rate (for example 0.1) for production traffic.
  • Or test on a separate n8n instance first.

To stop the export, turn tracing off again.

Keep the API key out of screenshots and prompts. Anyone with the key can send data to your project.

Self-hosted n8n

Set these variables on every n8n process: main, workers and webhook processors.

N8N_OTEL_ENABLED=true
N8N_OTEL_EXPORTER_OTLP_ENDPOINT=https://cloud.ratel.sh
N8N_OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
N8N_OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <your-ratel-key>
# Optional:
N8N_OTEL_TRACES_PRODUCTION_ONLY=false   # also trace manual runs (default: true)
N8N_OTEL_TRACES_SAMPLE_RATE=1.0         # fraction of executions to export

Restart n8n. Environment variables override the values in Settings > OpenTelemetry and lock those fields.

N8N_OTEL_EXPORTER_OTLP_TRACING_PATH defaults to /v1/traces, so you do not need to set it. To keep the key out of the environment, put the header string in a file and set N8N_OTEL_EXPORTER_OTLP_HEADERS_FILE to its path.

Docker Compose

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    ports:
      - "5678:5678"
    environment:
      N8N_OTEL_ENABLED: "true"
      N8N_OTEL_EXPORTER_OTLP_ENDPOINT: "https://cloud.ratel.sh"
      N8N_OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf"
      N8N_OTEL_EXPORTER_OTLP_HEADERS: "Authorization=Bearer ${RATEL_API_KEY}"
      N8N_OTEL_TRACES_PRODUCTION_ONLY: "false"
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Put RATEL_API_KEY=rtl_... in a .env file next to docker-compose.yml. Do not commit that file.

Through an OpenTelemetry Collector

Already run a collector? Point n8n at it and forward traces to Ratel:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlphttp/ratel:
    endpoint: https://cloud.ratel.sh   # the exporter adds /v1/traces
    headers:
      Authorization: "Bearer ${env:RATEL_API_KEY}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/ratel]

Then set N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://<collector-host>:4318 and leave out the header. Keep each export under 4 MB.

Check it works

  1. In n8n, click Send test trace. A success message means Ratel accepted the span.
  2. Run a workflow. n8n traces only published workflows unless you turned off Track published workflows only.
  3. In Ratel Cloud, open your project's Traces page. Find the trace by its time. Spans arrive when each node ends.
  4. For an AI Agent workflow on n8n 2.46 or later, open the dashboard. The model calls show the model, tokens and cost.

A workflow with no AI node has no model calls. Empty token and cost charts are expected for it.

To test the key from a terminal, send one span as shown in Send telemetry.

Query traces from your agent (MCP)

Ratel Cloud has an MCP server. A coding agent or an n8n MCP Client Tool node can read your traces through it.

SettingValue
Endpointhttps://cloud.ratel.sh/api/mcp
TransportHTTP Streamable
AuthenticationAuthorization: Bearer <your-ratel-key>

In Claude Code:

claude mcp add --transport http ratel https://cloud.ratel.sh/api/mcp \
  --header "Authorization: Bearer $RATEL_API_KEY"

Useful tools:

  • whoami: the project your key reaches.
  • list_traces, get_trace: find and read traces.
  • get_traces_ingest_diagnostics: why traces do not arrive.

The MCP server reads your data. It does not send telemetry. A tool that answers forbidden is not on for your organization yet: ask Ratel to turn it on.

Troubleshooting

SymptomFix
Test trace fails with 401The key is wrong or revoked. The header value must be Bearer <key>, with one space.
Test trace fails with a connection errorCheck Protocol is HTTP (protobuf), not gRPC. Check the endpoint is https://cloud.ratel.sh with no path.
404/v1/traces is in both the endpoint and the trace path, or the trace path is empty. Put it in the trace path only.
Test trace works, runs do not showTurn off Track published workflows only, or run a published workflow. Check Trace sample rate is above 0.
Traces show, no model callsn8n is older than 2.46. Update n8n.
413The export is over 4 MB. Lower node spans or sampling.
429Monthly call limit reached. See Send telemetry.
Self-hosted: no spans at allThe log says Failed to connect to OpenTelemetry OTLP endpoint during startup. Check the variables are on every n8n process. Set N8N_LOG_LEVEL=debug for detail.

Limits

  • AI Agent node before n8n 2.46: no model, tokens or tool calls. Only workflow and node timing. On n8n Cloud, the instance owner can update in the Cloud console: Instance settings > n8n version. See Update your version.
  • No prompts or responses from the AI Agent node. n8n sends model, tokens and names only. So Ratel cannot break down what fills the context.
  • No cache tokens. n8n sends input and output tokens only. With prompt caching on (for example with Claude), the cost in Ratel can differ from your provider bill.
  • Tool calls need n8n 3.2.2 or later (beta track at the time of writing). Tool spans carry the tool name only, not the arguments or the result.
  • n8n Agents (the Agents tab, not the AI Agent node) send richer spans: agent runs, model steps with tokens, and tool calls with arguments and results. See n8n's agent tracing.
  • n8n Cloud plans. If your instance has no Settings > OpenTelemetry page, ask n8n support whether your plan includes it.

Self-hosted alternative: LangSmith, then import

On self-hosted n8n, the AI Agent node can also send full LangChain runs to LangSmith. These runs include prompts, responses and tool calls. n8n Cloud does not support this.

  1. Set LANGCHAIN_TRACING_V2=true, LANGCHAIN_API_KEY=<langsmith-key> and, optionally, LANGCHAIN_PROJECT=<project> on n8n. Restart n8n.
  2. In Ratel Cloud, open Agent health and click Import past runs.
  3. Pick LangSmith, your region, your LangSmith API key and the project name.

Imports read past runs on demand. They are not a live feed. See Tool calls in imported runs.

Reference

On this page