OpenTelemetry 追踪#

此功能仍在开发中

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

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

功能可用性

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

观看 n8n 中 OpenTelemetry 追踪的概览：

可获得的内容#

开启追踪后，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。

在 UI 中启用追踪#

自 n8n v2.27.0 起可用

您需要是实例 Owner 或 Admin 才能在 UI 中配置 OpenTelemetry。

您可以从 Settings 设置 > OpenTelemetry 配置追踪，无需设置环境变量。n8n 不必重启即可应用更改，并会在队列模式下将更改重新加载到所有 worker 和 webhook 处理器。

配置追踪：

选择 Settings 设置 > OpenTelemetry。
打开 Enable OpenTelemetry 启用 OpenTelemetry。
在 Collector connection 收集器连接下输入 OTLP endpoint OTLP 端点及其他连接信息。
在 Tracing 追踪下设置采样和 span 选项。
选择 Save settings 保存设置。

要检查 n8n 能否连接收集器，请选择 Verify configuration 验证配置下的 Send test trace 发送测试追踪。n8n 会发送一个测试 span，并报告收集器是否已接收。保存前后都可以执行此测试。

每个字段都映射到一个环境变量，具体变量会显示在字段的工具提示中。完整列表请参阅 OpenTelemetry 环境变量。

环境变量优先

如果使用环境变量设置某个选项，n8n 会采用该值，并禁用 UI 中的对应字段。要从 UI 管理设置，请不要设置对应的环境变量。n8n 重启时，环境变量会覆盖 UI 中保存的值。

使用环境变量启用追踪#

在每个需要启用工作流追踪的 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 要么全部被采样，要么全部被丢弃。

Note

默认情况下，n8n 只为生产执行输出追踪。若要为所有工作流执行输出追踪，请设置 N8N_OTEL_TRACES_PRODUCTION_ONLY=false。

减少 span 数量#

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

export N8N_OTEL_TRACES_INCLUDE_NODE_SPANS=false

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

export N8N_OTEL_TRACES_INJECT_OUTBOUND=false

自定义 span 属性#

你可以为项目、工作流和节点 span 添加自定义属性。n8n 会将每个自定义属性作为 OpenTelemetry span 属性导出到你配置的可观测性后端。

功能可用性

自定义 span 属性适用于 Enterprise 计划。

不要在属性值中包含密钥、个人数据或其他敏感值。

n8n 支持以下自定义属性层级：

层级	配置位置	导出的 span	属性前缀
项目	Project settings 项目设置	`workflow.execute`	`n8n.project.custom.<key>`
工作流	Workflow settings 工作流设置	`workflow.execute`	`n8n.workflow.custom.<key>`
节点	节点的 Settings 设置选项卡	`node.execute`	`n8n.node.custom.<key>`

项目和工作流自定义 span 属性从 n8n 2.24.0 起可用。节点自定义 span 属性从 n8n 2.22.0 起可用。

添加项目 span 属性#

要添加项目级 span 属性：

打开项目。
选择 Project settings 项目设置。
在 Custom Span Attributes 自定义 span 属性下，添加一个或多个 span 属性。
选择 Save 保存。

项目属性值请使用纯文本。

添加工作流 span 属性#

要添加工作流级 span 属性：

打开工作流。
打开 Workflow settings 工作流设置。
在 Custom Span Attributes 自定义 span 属性下，选择 Configure 配置。
添加一个或多个 span 属性。
选择 Save 保存。

工作流属性值请使用纯文本。

添加节点 span 属性#

要添加节点级 span 属性：

打开节点并选择 Settings 设置选项卡。
在 Custom Span Attributes 自定义 span 属性下，选择 Add Attribute 添加属性。
输入 Key 键。键必须是纯文本。
输入 Value 值。值可以是纯文本或表达式，例如 ={{ $json.environment }}。

节点属性值必须解析为字符串、数字或布尔值。

在自定义节点中以编程方式添加属性#

如果你正在构建自定义节点，可以从代码中附加自定义键值对。在节点的 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 增补领域特定数据的节点作者。

如果节点在此处设置了一个也配置为自定义节点 span 属性的属性键，则以编程方式设置的值优先。

使用 Jaeger 试用#

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

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

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

启动 Jaeger：

docker compose up -d

启动已开启追踪并指向 Jaeger 的 n8n。设置详情请参阅启动 n8n：

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

运行一个工作流，然后打开 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.project.id`	项目 ID。从 n8n `2.23.0` 起可用。
`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 上的原因。
`n8n.project.custom.<key>`	通过项目级自定义 span 属性设置的自定义属性。
`n8n.workflow.custom.<key>`	通过工作流级自定义 span 属性设置的自定义属性。

节点 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>`	通过节点设置中的节点级自定义 span 属性或自定义节点代码中的 `metadata.tracing` 设置的自定义属性。

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

故障排查#

后端中没有看到任何追踪#

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

1	`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 以查看更多细节。

缺少自定义 span 属性#