OpenTelemetry 追踪

此功能仍在开发中

• 首次提供于 2.19.0
• OpenTelemetry 格式的指标支持即将推出

n8n 可以为工作流和节点执行发出 OpenTelemetry 追踪。你可以利用这些追踪监控执行延迟、调试失败问题，并在可观测性体系中跟踪跨服务请求。

功能可用性

OpenTelemetry 工作流追踪仅适用于自托管 n8n。

可获得的内容

开启追踪后，n8n 会为每次执行导出两类 span：

• workflow.execute：每次工作流执行对应一个 span。它会记录工作流 ID、名称、版本、节点数量、执行模式、状态以及错误类型（如果有）。
• node.execute：每次节点执行对应一个 span，嵌套在所属工作流 span 之内。它会记录节点 ID、名称、类型、版本以及输入/输出数据项数量。

每个 span 都会包含用于标识 n8n 实例的资源属性：

• service.name (default n8n)
• service.version（n8n 版本）
• n8n.instance.id
• n8n.instance.role（例如 main、worker 或 webhook）

n8n 还会处理追踪上下文传播：

• Inbound 入站：如果某个 webhook 请求包含 W3C traceparent 头，n8n 会将其作为工作流 span 的父级。这样就能把 n8n 工作流追踪接入上游调用方的追踪链路。
• Outbound 出站：HTTP Request 节点（以及其他使用 n8n HTTP helper 的节点）可以在出站请求中注入 traceparent 头。支持 W3C 追踪上下文的下游服务因此可以继续这条追踪链路。
• Sub-workflows 子工作流：子工作流的 span 会以父工作流的 span 作为父级。
• Resumed workflows 恢复执行的工作流：当工作流在等待后恢复执行时，新 span 会通过 span link 关联回上一个 span。

启用追踪

在每个需要启用工作流追踪的 n8n 实例上设置以下环境变量，包括主实例、worker 和 webhook 处理器：

export N8N_OTEL_ENABLED=true
export N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://<your-collector-host>:4318

重启 n8n 后，该实例会开始通过 OTLP HTTP 以 Protobuf 编码导出 span。

n8n 默认会把 /v1/traces 追加到端点后面。因此 N8N_OTEL_EXPORTER_OTLP_ENDPOINT 应指向 collector 的基础 URL，而不是 traces 路径本身。

如果你的 collector 需要认证，可将 N8N_OTEL_EXPORTER_OTLP_HEADERS 设为逗号分隔的 key=value 列表：

export N8N_OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <your-token>,x-tenant=acme"

// 为了进一步保护，如果这里放的是 token，建议改用 `_FILE` 后缀：
export N8N_OTEL_EXPORTER_OTLP_HEADERS_FILE=/mnt/otel-headers

支持的全部变量请参阅 OpenTelemetry 环境变量。

队列模式

在队列模式下，必须在所有实例上设置 OpenTelemetry 变量。追踪上下文会在实例之间传播。

采样

默认情况下，n8n 会导出每一条追踪。若要减少高负载实例中的追踪量，可将 N8N_OTEL_TRACES_SAMPLE_RATE 设为 0 到 1 之间的值：

# 导出 10% 的追踪
export N8N_OTEL_TRACES_SAMPLE_RATE=0.1

n8n 使用 trace ID 比例采样器，因此同一个 trace ID 对应的整条追踪中的所有 span 要么全部被采样，要么全部被丢弃。

n8n 会为每次工作流执行输出一条追踪，包括已发布工作流、未发布工作流以及测试执行。未来版本会提供一个开关，用于仅追踪已发布工作流。

减少 span 数量

工作流中的每个节点都会生成自己的 span。对于节点较多的工作流，这可能会产生超出你所需的数据量。若只想导出工作流级 span，请设置：

export N8N_OTEL_TRACES_INCLUDE_NODE_SPANS=false

如果你想阻止 n8n 向出站 HTTP 请求注入 traceparent 头，请设置：

export N8N_OTEL_TRACES_INJECT_OUTBOUND=false

为节点 span 添加自定义属性

如果你正在构建自定义节点，可以为该节点的 span 添加自定义键值对。在节点的 execute 方法中调用 setMetadata：

async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
	this.setMetadata({
		tracing: {
			'llm.model': 'gpt-4o',
			'llm.token.input': 1500,
			'llm.token.output': 340,
		},
	});

	return [this.getInputData()];
}

n8n 会在导出的 span 上为每个键自动加上 n8n.node.custom. 前缀。值必须是字符串、数字或布尔值。

这个 API 不适用于 Code 节点。它面向想为 span 增补领域特定数据的节点作者。

使用 Jaeger 试用

你可以将追踪发送到本地 Jaeger 实例，实际查看它们的效果。

1. 将以下内容保存为 docker-compose.yml：

services:
  jaeger:
    image: jaegertracing/jaeger:latest
    ports:
      - "16686:16686" # UI
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP

2. 启动 Jaeger：

docker compose up -d

3. 启动已开启追踪并指向 Jaeger 的 n8n。关于启动 n8n 的更多信息，可在本文档其他页面中找到：

N8N_OTEL_ENABLED=true N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 n8n start

5. 运行一个工作流，然后打开 Jaeger UI：http://localhost:16686。选择服务 n8n，再点击 Find traces，即可查看 n8n 发出的 OpenTelemetry 追踪。

Span 属性

工作流 span 和节点 span 会包含以下 n8n 特有属性。

工作流 span（workflow.execute）

属性	说明
n8n.workflow.id	工作流 ID。
n8n.workflow.name	工作流名称。
n8n.workflow.version_id	工作流版本 ID。
n8n.workflow.node_count	工作流中的节点数量。
n8n.execution.id	执行 ID。
n8n.execution.mode	执行模式（例如 manual、webhook、trigger、retry）。
n8n.execution.status	最终执行状态。
n8n.execution.is_retry	若本次执行为重试，则值为 true。
n8n.execution.retry_of	如果本次执行是重试，对应原始执行的 ID。
n8n.execution.error_type	执行失败时设置的错误类名。
n8n.continuation.reason	当工作流在等待后恢复执行时，写入到 span link 上的原因。

节点 span（node.execute）

属性	说明
n8n.node.id	节点 ID。
n8n.node.name	节点名称。
n8n.node.type	节点类型（例如 n8n-nodes-base.httpRequest）。
n8n.node.type_version	节点类型版本。
n8n.node.items.input	节点收到的输入数据项数量。
n8n.node.items.output	节点输出的数据项数量。
n8n.node.termination_reason	节点 span 未正常完成而结束的原因（例如 workflow_cancelled）。
n8n.node.custom.<key>	通过节点输出中的 metadata.tracing 设置的自定义属性。

当节点失败时，n8n 会在 span 上记录一个 exception 事件，并附带标准 OpenTelemetry 异常属性（exception.type、exception.message、exception.stacktrace）。

故障排查

后端中没有看到任何追踪

如果 n8n 在启动时无法访问 OTLP 端点，会记录以下错误：

Failed to connect to OpenTelemetry OTLP endpoint during startup

请检查：

• N8N_OTEL_ENABLED is set to true.
• N8N_OTEL_EXPORTER_OTLP_ENDPOINT 是否指向 collector 的基础 URL（而不是 /v1/traces 路径）。
• n8n 所在容器或主机是否能够访问 collector。
• 是否已设置所需的 N8N_OTEL_EXPORTER_OTLP_HEADERS（例如认证 token）。

n8n 默认以 warn 级别输出 OpenTelemetry 诊断日志。可设置 N8N_LOG_LEVEL=debug 以查看更多细节。

Worker 追踪缺少父级上下文

在队列模式下，worker 会从数据库读取父级追踪上下文。如果你只在主实例上设置了 OpenTelemetry 环境变量，worker span 将无法关联到父工作流追踪。请在每种实例类型上都设置相同变量。

相关资源

• OpenTelemetry 环境变量
• W3C Trace Context specification
• OpenTelemetry Collector documentation
• n8n 中的日志
• 监控