> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# n8n
> Export n8n workflow, node, and agent OpenTelemetry spans to Arize AX over OTLP.
[n8n](https://n8n.io/) can export workflow and node execution traces over OTLP. Recent n8n versions can also emit agent spans using OpenTelemetry GenAI semantic conventions. Send these spans to Arize AX to inspect workflow latency, node failures, and agent behavior.
n8n OpenTelemetry tracing is marked preview in n8n's documentation. OTEL tracing is available from n8n `2.19.0`, UI-based OTEL configuration is available from `2.27.0`, and agent tracing is available from `2.33.0`. Validate the behavior on your n8n version before relying on it for production operations.
## Prerequisites
* A self-hosted n8n instance with OpenTelemetry tracing support. Use n8n `2.19.0` or later for workflow tracing and `2.33.0` or later for agent tracing.
* An Arize AX account ([sign up](https://arize.com/sign-up/))
* Your Arize AX **Space ID** and **API Key**
## Launch Arize AX
1. Sign in to your [Arize AX account](https://app.arize.com/).
2. From **Space Settings**, copy your **Space ID** and **API Key**.
## Configure n8n with environment variables
Set these variables on each n8n process that should emit traces, including main, worker, and webhook processors in queue mode:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export N8N_OTEL_ENABLED=true
export N8N_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.arize.com
export N8N_OTEL_EXPORTER_OTLP_TRACING_PATH=/v1/traces
export N8N_OTEL_EXPORTER_OTLP_HEADERS="space_id=,api_key="
export N8N_OTEL_EXPORTER_SERVICE_NAME=n8n
```
For EU spaces, use:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export N8N_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.eu-west-1a.arize.com
```
Restart n8n after setting the environment variables.
n8n appends `N8N_OTEL_EXPORTER_OTLP_TRACING_PATH` to `N8N_OTEL_EXPORTER_OTLP_ENDPOINT`. Set the endpoint to the base Arize host and the tracing path to `/v1/traces`.
For production deployments, you can use n8n's `_FILE` variants for sensitive values when your deployment platform mounts secrets as files.
## Enable n8n agent tracing
In n8n `2.33.0` or later, enable agent spans:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export N8N_AGENTS_TRACING_ENABLED=true
```
By default, n8n agent tracing may record prompts, tool arguments, responses, and tool results. To reduce sensitive data capture:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export N8N_AGENTS_TRACING_RECORD_INPUTS=false
export N8N_AGENTS_TRACING_RECORD_OUTPUTS=false
```
## Verify in Arize
1. Run an n8n workflow.
2. Open your Arize AX space.
3. Look for `workflow.execute` and `node.execute` spans within \~30 seconds. Agent runs may also appear as GenAI spans if enabled.
If you configured OpenTelemetry from the n8n UI, use n8n's **Send test trace** action to verify the exporter before running a workflow.
### Check from the skill, CLI, or SDK
Confirm spans are actually reaching your Arize AX project. Use whichever fits your workflow — the skill and CLI work for any framework; the SDK check is shown for each language.
Install the [Arize Skills](https://github.com/Arize-ai/arize-skills) plugin and let your coding agent check for you:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npx skills add Arize-ai/arize-skills
```
Then prompt your agent:
> Use the `arize-trace` skill to export and analyze recent traces from my project. Confirm spans are arriving, and summarize any errors or latency issues.
Export recent spans for your project — any rows mean traces are landing:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax spans export "$ARIZE_PROJECT_NAME" --space "$ARIZE_SPACE_ID" \
--limit 5 --stdout | jq 'length'
```
A non-zero count confirms spans reached Arize AX. Run `ax auth login` first if you have not authenticated. See the [`ax spans` reference](/docs/api-clients/cli/spans).
Query the project's spans and check that at least one came back.
```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import os
from arize import ArizeClient
client = ArizeClient(api_key=os.environ["ARIZE_API_KEY"])
resp = client.spans.list(
project=os.environ["ARIZE_PROJECT_NAME"],
space=os.environ["ARIZE_SPACE_ID"],
limit=5,
)
count = len(resp.spans)
print(
f"{count} span(s) found" if count else "No spans yet — recheck setup"
)
```
```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// Reads ARIZE_API_KEY from the environment.
import { listSpans } from "@arizeai/ax-client";
const { data: spans } = await listSpans({
project: process.env.ARIZE_PROJECT_NAME!,
space: process.env.ARIZE_SPACE_ID!,
limit: 5,
});
const count = spans.length;
console.log(
count ? `${count} span(s) found` : "No spans yet — recheck setup",
);
```
```go Go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
client, err := arize.NewClient(
arize.Config{APIKey: os.Getenv("ARIZE_API_KEY")},
)
if err != nil {
log.Fatal(err)
}
resp, err := client.Spans.List(ctx, spans.ListRequest{
Project: os.Getenv("ARIZE_PROJECT_NAME"),
Space: os.Getenv("ARIZE_SPACE_ID"),
Limit: 5,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%d span(s) found\n", len(resp.Spans))
```
SDK span references: [Python](/docs/api-clients/python/version-8/client-resources/spans) · [TypeScript](/docs/api-clients/typescript/version-1/client-resources/spans) · [Go](/docs/api-clients/go/version-2/client-resources/spans).
## What Arize captures
n8n exports:
* `workflow.execute` spans for workflow executions
* `node.execute` spans for node executions
* W3C trace context propagation for inbound webhooks and outbound HTTP requests
* agent spans using OpenTelemetry GenAI semantic conventions when `N8N_AGENTS_TRACING_ENABLED=true`
## Optional: add a project name with an OpenTelemetry Collector
Arize AX uses the `openinference.project.name` resource attribute to organize traces into projects. n8n's direct OTLP configuration focuses on endpoint, headers, service name, sampling, and span options. If you want a specific project name, send n8n traces through an OpenTelemetry Collector and add:
```yaml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
processors:
resource/arize_project:
attributes:
- key: openinference.project.name
value: n8n
action: upsert
```
Then export to Arize AX with the same `space_id` and `api_key` headers.
## Troubleshooting
* **No traces in Arize.** Confirm `N8N_OTEL_ENABLED=true`, the endpoint is the base Arize OTLP host, the tracing path is `/v1/traces`, and headers include `space_id` and `api_key`.
* **Only production executions appear.** n8n exports production executions by default. Set `N8N_OTEL_TRACES_PRODUCTION_ONLY=false` to trace all executions.
* **Node spans are missing.** Confirm `N8N_OTEL_TRACES_INCLUDE_NODE_SPANS=true`.
* **Agent spans are missing.** Confirm your n8n version supports agent tracing and `N8N_AGENTS_TRACING_ENABLED=true`.
## Resources