OpenTelemetry 跟踪
提示
预览状态
OpenTelemetry 跟踪处于 n8n 2.19.0 的预览版中,并且可能在未来版本中发生变化。避免在生产工作流程中依赖它。 n8n 计划在后续版本中添加 OpenTelemetry 格式的指标。
n8n 可以发出工作流和节点执行的 OpenTelemetry 跟踪。您可以使用这些跟踪监视执行延迟、调试故障,并在可观测性堆栈中跟踪跨服务请求。
观看 n8n 中 OpenTelemetry 跟踪的概述:
https://www.youtube.com/embed/xOi8K_-GLRM
您将得到什么
当您打开跟踪时,n8n 会为每次执行导出两种范围:
workflow.execute:每个工作流执行一个跨度。它记录工作流 ID、名称、版本、项目、节点数、执行模式、状态和任何错误类型。node.execute:每个节点执行一个跨度,嵌套在其工作流跨度内。它记录节点 ID、名称、类型、版本、输入和输出项的数量,以及它所属的执行、工作流和项目。
n8n 会在跨度结束时将其导出。要在运行仍在进行时看到它,请开启启动跨度。
每个范围都包含标识 n8n 实例的资源属性:
service.name(默认n8n)service.version(n8n 版本)n8n.instance.idn8n.instance.role(例如,main、worker或webhook)
n8n 还处理跟踪上下文传播:
- 入站:如果 Webhook 请求包含 W3C
traceparent标头,则 n8n 将其用作工作流跨度的父级。这会将 n8n 工作流程跟踪链接到上游调用方。从 n8n 2.47.0 开始,n8n 还会读取baggage标头。n8n 读取该标头只是为了转发它,因此必须开启 Send outbound trace headers。请参阅转发调用方 baggage。 - 出站:HTTP 请求节点(以及使用 n8n HTTP 帮助程序的其他节点)可以向出站请求添加
traceparent、tracestate和baggage标头。支持 W3C 跟踪上下文的下游服务可以继续跟踪。请参阅出站跟踪标头。 - 子工作流:子工作流的跨度使用父工作流的跨度作为其父级。
- 恢复工作流:当工作流在等待后恢复时,新的跨度使用跨度链接链接回之前的跨度。
在 UI 中启用跟踪
提示
功能可用性
从 n8n 2.27.0 开始,可以从 UI 配置 OpenTelemetry 跟踪。您需要是实例所有者或管理员才能在 UI 中配置 OpenTelemetry。
您可以从 设置 > OpenTelemetry 配置跟踪,而不是设置环境变量。 n8n 应用您的更改而无需重新启动,并在 队列模式 中的工作线程和 Webhook 处理器之间重新加载它们。
要配置跟踪:
- 选择 设置 > OpenTelemetry。
- 打开启用 OpenTelemetry。
- 在 收集器连接 下,输入您的 OTLP 端点 和任何其他连接详细信息。
- 在跟踪下,设置采样和跨度选项。
- 选择保存设置。
要检查 n8n 是否可以到达您的收集器,请选择 验证配置 下的 发送测试跟踪。 n8n 发送单个测试范围并报告收集器是否接受它。您可以在保存之前或之后运行它。
每个字段都映射到一个环境变量,如字段的工具提示中所示。有关完整列表,请参阅 OpenTelemetry 环境变量。
提示
环境变量优先
如果您使用环境变量设置选项,n8n 将使用该值并禁用 UI 中的匹配字段。要从 UI 管理设置,请保持其环境变量未设置。当 n8n 重新启动时,环境变量会覆盖 UI 中保存的值。
使用环境变量启用跟踪
在您想要启用工作流跟踪的每个 n8n 实例(主处理器、工作线程处理器和 Webhook 处理器)上设置以下环境变量:
export N8N_OTEL_ENABLED=true
export N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://<your-collector-host>:4318
重新启动 n8n。该实例会开始使用 Protobuf 编码通过 OTLP HTTP 导出 spans。要改用 gRPC 导出,请参阅选择 OTLP 协议。
默认情况下,n8n 将 /v1/traces 附加到端点。请将 N8N_OTEL_EXPORTER_OTLP_ENDPOINT 指向收集器的基础 URL,而不是跟踪路径。端点必须是 http:// 或 https:// URL。如果设置了其他协议或未设置协议,n8n 会记录警告并使用默认端点。
如果您的收集器需要身份验证,请将 N8N_OTEL_EXPORTER_OTLP_HEADERS 设置为以逗号分隔的 key=value 对列表:
export N8N_OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <your-token>,x-tenant=acme"
// For added protection - It is recommended to use the `_FILE` postfix if you are putting a token in here:
export N8N_OTEL_EXPORTER_OTLP_HEADERS_FILE=/mnt/otel-headers
有关支持的变量的完整列表,请参阅 OpenTelemetry 环境变量。
提示
队列模式
在 队列模式 中,必须在所有实例上设置 OpenTelemetry 变量。跟踪上下文在实例之间传播。
选择 OTLP 协议
提示
功能可用性
OTLP gRPC 协议及 Protocol 协议 设置和 N8N_OTEL_EXPORTER_OTLP_PROTOCOL 环境变量从 n8n 2.39.0 起可用。
n8n 可以通过两种 OTLP 传输协议导出跟踪:
http/protobuf(默认):使用 Protobuf 编码的 OTLP over HTTP。按照惯例,收集器在端口 4318 上侦听。它可以通过不支持 HTTP/2 的代理、入口和防火墙,也更容易调试。grpc:OTLP over gRPC。按照惯例,收集器在端口 4317 上侦听。HTTP/2 多路复用和二进制帧可降低每次导出的开销;这种差异在 span 数量很大时最为明显。整个链路都需要支持 HTTP/2,某些代理和负载均衡器需要显式配置 HTTP/2。
除非收集器只接受 gRPC,或要通过支持 HTTP/2 的基础设施导出大量跟踪,否则请保留默认的 http/protobuf。
要选择协议,请在 Settings 设置 > OpenTelemetry 中设置 Protocol 协议 字段,或设置环境变量:
export N8N_OTEL_EXPORTER_OTLP_PROTOCOL=grpc
变量名称及其值(http/protobuf 和 grpc)与上游 OTEL_EXPORTER_OTLP_PROTOCOL 规范一致。与 Settings 设置 > OpenTelemetry 中的其他字段一样,设置此环境变量后,n8n 会禁用 Protocol 协议 字段。
TLS
对于这两种协议,端点协议方案都会控制 TLS。https:// 会启用 TLS,http:// 会将其关闭。n8n 不接受 grpc:// 协议方案。
要信任自定义证书颁发机构,或提供用于双向 TLS(mTLS)的客户端证书,请使用上游 OpenTelemetry 变量 OTEL_EXPORTER_OTLP_CERTIFICATE、OTEL_EXPORTER_OTLP_CLIENT_KEY 和 OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE。使用 http/protobuf 协议时,也可以使用 NODE_EXTRA_CA_CERTS。n8n 没有自己的证书设置。
gRPC 行为
grpc 协议与 http/protobuf 存在以下差异:
- 在端点中包含端口。 未显式指定端口的 gRPC 端点会连接到 gRPC 默认端口 443,而不是 4317。请写成
http://<your-collector-host>:4317。 - gRPC 端点不带 URL 路径。 n8n 会忽略 Trace path 跟踪路径 设置(
N8N_OTEL_EXPORTER_OTLP_TRACING_PATH)并在 UI 中隐藏对应行。n8n 会保留保存的值;切换回http/protobuf后会再次应用该值。 - 自定义标头会成为 gRPC metadata。 n8n 会将 key 转换为小写。它会跳过 gRPC 拒绝的条目(包括带有文本值且以
-bin结尾的 key),并记录警告而不是导致启动失败。 - 启动连接检查会等待 gRPC 通道就绪。 通道就绪证明 n8n 可以打开 TCP 连接、为
https://完成 TLS 握手并建立 HTTP/2 连接,但不能证明该端点提供 OTLP 服务。请在 Settings 设置 > OpenTelemetry 中使用 Send test trace 发送测试跟踪 确认收集器能收到 spans。此检查不会阻止启动。
采样
默认情况下,n8n 导出每条轨迹。要减少繁忙实例中的音量,请将 N8N_OTEL_TRACES_SAMPLE_RATE 设置为 0 和 1 之间的值:
# Export 10% of traces <a href="#export-10percent-of-traces" id="export-10percent-of-traces"></a>
export N8N_OTEL_TRACES_SAMPLE_RATE=0.1
n8n 使用迹线 ID 比率采样器,因此同一迹线 ID 在迹线中的所有跨度上要么完全采样,要么完全丢弃。
提示
默认情况下,n8n 仅输出 生产执行 的迹线。要输出所有工作流程执行的跟踪,请设置 N8N_OTEL_TRACES_PRODUCTION_ONLY=false。
减少跨度体积
工作流中的每个节点都会生成自己的跨度。对于具有大量节点的工作流程,这可能会产生超出您需要的数据。要仅导出工作流程级别跨度,请设置:
export N8N_OTEL_TRACES_INCLUDE_NODE_SPANS=false
出站跟踪标头
提示
功能可用性
在出站请求中发送 baggage 标头以及 OTEL_PROPAGATORS 环境变量从 n8n 2.47.0 起可用。
Send outbound trace headers 决定 n8n 是否向出站请求添加任何跟踪标头,默认开启。可以在 Settings > OpenTelemetry 下设置,也可以使用 N8N_OTEL_TRACES_INJECT_OUTBOUND 环境变量设置。与 Settings > OpenTelemetry 中的其他字段一样,设置了该环境变量后,n8n 会禁用该字段。
OTEL_PROPAGATORS 指定开关开启时 n8n 写入哪些标头:
N8N_OTEL_TRACES_INJECT_OUTBOUND |
OTEL_PROPAGATORS |
n8n 发送的标头 |
|---|---|---|
| 关闭 | 任意值 | 无 |
| 开启 | 未设置 | traceparent、tracestate、baggage |
| 开启 | tracecontext |
traceparent、tracestate |
| 开启 | baggage |
baggage |
| 开启 | none |
无 |
只有当跟踪包含 tracestate 时,n8n 才会发送它;只有当执行包含条目时,才会发送 baggage。
OTEL_PROPAGATORS 是标准的 OpenTelemetry 变量。它接受以逗号分隔的名称列表,默认值为 tracecontext,baggage,不区分大小写。对于不支持的名称(例如 b3),n8n 会忽略并记录警告。
它只影响出站标头,不会改变 n8n 从入站请求中读取的内容。
n8n 只在启动时读取一次 OTEL_PROPAGATORS,因此更改后需要重启。Send outbound trace headers 开关则无需重启即可生效。
要阻止 n8n 发送任何跟踪标头:
export N8N_OTEL_TRACES_INJECT_OUTBOUND=false
要保留跟踪上下文但不发送 baggage 标头:
export OTEL_PROPAGATORS=tracecontext
转发调用方 baggage
当 webhook 请求带有 W3C baggage 标头时,n8n 会在该执行发出的出站请求中转发这些条目。这样,下游服务就可以将相同的条目(例如租户 ID)放到自己的遥测数据中。
转发需要开启 OpenTelemetry、开启 Send outbound trace headers,并且 propagators 中包含 baggage。
警告
调用方的 baggage 会离开你的实例
n8n 会将调用方的条目转发给该执行调用的每个主机,包括第三方 API。子工作流或错误工作流会发送启动它的那次运行的 baggage。这些条目来自调用方,因此 n8n 无法判断它们是否可以安全共享。要保留跟踪上下文并丢弃调用方的条目,请设置 OTEL_PROPAGATORS=tracecontext。
n8n 处理这些条目的方式:
- n8n 会丢弃所有键以
n8n.开头的条目。该前缀保留给 n8n 自己的属性,因此调用方无法伪造。 - n8n 会丢弃超出 OpenTelemetry 限制的条目:180 个条目、单个条目 4,096 字节、总计 8,192 字节。被丢弃的条目永远不会到达下游服务。
- n8n 会将这些条目保存在执行上,因此它们在队列模式的 worker 中以及在 Wait 节点之后恢复时都会保留。
- n8n 转发这些条目但不会记录它们。
tenant.id条目会随标头发出,但永远不会作为跨度属性出现。 otel.configure外部钩子可以添加自己的条目。当二者设置了相同的键时,钩子的条目优先于调用方的条目。
启动跨度
提示
功能可用性
启动跨度从 n8n 2.44.0 起可用。
在跨度结束之前,长时间运行的工作流或节点在后端不可见。开启启动跨度后,n8n 还会在工作流或节点启动时发送一个持续时间为 0 毫秒的子跨度。启动跨度会携带其父跨度在该时刻的相同属性,因此你可以立即知道正在运行的内容,以及它所属的工作流和项目。
| 启动跨度 | 父跨度 | 设置 | 环境变量 |
|---|---|---|---|
workflow.execute.started |
workflow.execute |
Send workflow start spans 发送工作流启动跨度 | N8N_OTEL_TRACES_EMIT_WORKFLOW_START_SPAN |
node.execute.started |
node.execute |
Send node start spans 发送节点启动跨度 | N8N_OTEL_TRACES_EMIT_NODE_START_SPAN |
两者默认均关闭。可在 Settings 设置 > OpenTelemetry > Tracing 跟踪下开启它们,或将环境变量设为 true。节点启动跨度还需要开启 Include node spans 包含节点跨度(N8N_OTEL_TRACES_INCLUDE_NODE_SPANS)。在队列模式下,请在主实例和每个 worker 上设置这些变量。
要使用公共 API,请使用具有 otel:manage scope 的 API key 调用 PUT /api/v1/settings/otel,并传入 emitWorkflowStartSpan 和 emitNodeStartSpan。此调用会替换所有 OpenTelemetry 设置。n8n 会拒绝缺少必填字段的请求体。如果省略可选字段 exporterProtocol、emitWorkflowStartSpan 或 emitNodeStartSpan,n8n 会将其重置为默认值。
崩溃的执行
提示
功能可用性
从 n8n 2.42.0 开始,可以为崩溃的执行生成跨度。
如果运行某个执行的 n8n 实例停止且未记录结果,例如因内存不足而被终止或容器被驱逐,该执行会被标记为 crashed。n8n 在发现该执行无法完成后,才会将其标记为 crashed。在 n8n 2.42.0 之前,这类执行不会生成跨度,因此跟踪后端中的错误率会漏掉所有平台故障。从 n8n 2.42.0 开始,崩溃的执行会生成一个 workflow.execute 跨度。
接收崩溃跨度
发出跨度的是检测到崩溃的实例,而不是运行该执行的实例。在队列模式下,检测崩溃的是主实例,因此请在主实例上启用 OpenTelemetry,而不只是工作线程。在常规模式下,单个主实例会运行并检查自己的执行,因此常规设置已涵盖这种情况。
读取崩溃跨度
崩溃跨度包含常规的工作流跨度属性,以及以下属性:
| 属性 | 值 |
|---|---|
n8n.execution.status |
crashed |
n8n.execution.error_type |
WorkflowCrashedError |
n8n.execution.crash.detector |
发现崩溃的检查。请参阅 n8n 如何检测崩溃。 |
n8n.execution.reconstructed |
n8n 结束原始跨度时为 false,重建跨度时为 true。请参阅已跟踪和重建的跨度。 |
该跨度的状态为 error,并带有一个 exception 事件。
n8n 如何检测崩溃
| 检测器 | 含义 |
|---|---|
stall |
队列模式。工作线程停止续订其作业锁。 |
queue-recovery |
队列模式。定期检查发现某个正在运行的执行在队列中没有对应作业。 |
startup-recovery |
n8n 重启后发现某个执行仍标记为正在运行。 |
start-failure |
执行无法启动。 |
workflow-deactivation |
工作流仍有执行正在进行时,有人取消了该工作流的发布。 |
已跟踪和重建的跨度
启动执行的实例会打开其 workflow.execute 跨度。如果同一实例检测到崩溃,它会就地结束该跨度,并设置 n8n.execution.reconstructed=false。该跨度会保留启动时设置的所有属性。该实例上仍处于打开状态的节点跨度会以 n8n.node.termination_reason=workflow_crashed 结束。
如果由另一个实例检测到崩溃(例如主实例重启后),则不存在打开的跨度。n8n 会根据执行中存储的跟踪上下文,在同一跟踪中重建一个 workflow.execute 跨度,并设置 n8n.execution.reconstructed=true。重建的跨度包含工作流 ID、工作流名称、工作流版本 ID、项目 ID、项目和工作流的自定义跨度属性、执行 ID、执行模式、n8n.execution.is_retry 和 n8n.execution.retry_of,但缺少以下内容:
n8n.workflow.node_count。- 它自身的节点跨度。崩溃前已导出的节点跨度会保留在跟踪中。实例停止时正在运行的节点没有跨度。
- 执行从等待状态恢复时,指向前一个跨度的跨度链接。
其工作流自定义属性来自工作流的当前设置,而不是运行时所用版本的设置。
崩溃执行的注意事项
- 持续时间表示检测延迟,而不是运行时间。 崩溃跨度在 n8n 检测到崩溃时结束,而不是在实例停止时结束。
stall的延迟为一到两分钟,queue-recovery要等到下一次定期检查,startup-recovery则要等到下一次重启。请从延迟指标中排除n8n.execution.status=crashed的跨度,仅在错误率指标中统计它们。 - 重建的跨度会显示缺少父跨度。 存储的跟踪上下文是原始跨度的 ID,而 OpenTelemetry 无法重复使用跨度 ID。因此,重建的跨度会成为从未结束的跨度的子级,Jaeger 和类似后端会将其标记为缺少父跨度。此警告属于预期行为。
- 停滞的队列作业状态已更改。 在 n8n 2.42.0 之前,工作线程停止的作业会以
error状态结束。从 n8n 2.42.0 开始,它会以crashed状态结束,检测器为stall。仅匹配n8n.execution.status=error的告警会漏掉这类作业。
代理追踪
提示
功能可用性
从 n8n 2.33.0 开始可以使用代理跟踪。
n8n 还可以使用与工作流跟踪相同的跟踪器,为通过 Agents 功能构建的代理运行发出详细跨度。这涵盖从工作流、聊天集成和计划任务启动的代理运行。
警告
旧版 AI Agent 节点
本节介绍新 Agents 功能的跟踪。旧版 AI Agent(LangChain)节点只会像其他节点一样生成标准的 node.execute 跨度,不会生成 gen_ai.* 代理运行或工具调用跨度。
代理跟踪与 OTel 模块的其余部分一起运行。开启 N8N_OTEL_ENABLED 后,添加:
export N8N_AGENTS_TRACING_ENABLED=true
将其设置为 false 以保留工作流和节点跨度,同时删除代理跨度。
默认情况下,代理跟踪记录提示、工具参数、响应和工具结果。要排除敏感输入或输出数据:
export N8N_AGENTS_TRACING_RECORD_INPUTS=false
export N8N_AGENTS_TRACING_RECORD_OUTPUTS=false
有关变量的完整列表,请参阅 OpenTelemetry 环境变量。
您将得到什么
每个代理运行都会生成一个根跨度,名为 <agent name>.generate 或 <agent name>.stream,具体取决于运行是否流式传输其响应。代理调用的每个工具都会生成一个嵌套的 execute_tool <tool name> 跨度。
这些跨度使用 OpenTelemetry GenAI 语义约定(gen_ai.* 属性),因此它们可以在任何 OTLP 后端中读取,而不仅仅是为 LangSmith 构建的工具。
自定义跨度属性
您可以将自定义属性添加到项目、工作流和节点范围。 n8n 将每个自定义属性作为 OpenTelemetry 范围属性导出到您配置的可观察性后端。
提示
功能可用性
自定义跨度属性可用于:
- 自托管: 企业
它们在 n8n Cloud 上不可用。
项目和工作流程自定义跨度属性可从 n8n 2.24.0 开始使用。从 n8n 2.22.0 开始,可以使用节点自定义跨度属性。
不要在属性值中包含机密、个人数据或其他敏感值。
n8n 支持以下自定义属性级别:
| 级别 | 配置位置 | 导出范围 | 默认属性前缀 |
|---|---|---|---|
| 项目 | 项目设置 | workflow.execute |
n8n.project.custom.<key> |
| 工作流程 | 工作流程设置 | workflow.execute |
n8n.workflow.custom.<key> |
| 节点 | 节点 设置 选项卡 | node.execute |
n8n.node.custom.<key> |
添加项目跨度属性
要添加项目级跨度属性:
- 打开一个项目。
- 选择项目设置。
- 在“自定义跨度属性”下,添加一个或多个跨度属性。
- 选择保存。
使用纯文本作为项目属性值。
添加工作流跨度属性
要添加工作流级别跨度属性:
- 打开工作流程。
- 打开工作流程设置。
- 在“自定义跨度属性”下,选择“配置”。
- 添加一个或多个跨度属性。
- 选择保存。
使用纯文本作为工作流属性值。
添加节点跨度属性
添加节点级跨度属性:
- 打开节点并选择 设置 选项卡。
- 在“自定义跨度属性”下,选择“添加属性”。
- 输入密钥。密钥必须是纯文本。
- 输入值。值可以是纯文本或表达式,例如
={{ $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 会为每个键添加 n8n.node.custom. 前缀。你可以更改属性前缀。值必须是字符串、数字或布尔值。
此 API 无法从代码节点获得。它适用于想要使用特定于域的数据丰富跨度的节点作者。
如果节点在此处设置的属性键也配置为 自定义节点跨度属性,则编程值优先。
更改属性前缀
提示
功能可用性
自 n8n 2.46.0 起,可以自定义属性前缀。
n8n 会为自定义属性键添加前缀。要更改或移除前缀,请将 N8N_OTEL_TRACES_CUSTOM_ATTRIBUTE_PREFIXES 设置为 JSON 对象。该对象接受以下键,且每个键的值都必须是字符串:
| 键 | 设置以下属性的前缀 | 默认前缀 |
|---|---|---|
project |
项目属性 | n8n.project.custom. |
workflow |
工作流属性 | n8n.workflow.custom. |
node |
节点属性 | n8n.node.custom. |
空字符串会移除前缀。未提供的键会保留其默认前缀。请在主实例、工作线程和 webhook 处理器上设置相同的值。
要移除项目和节点属性的前缀,并完全按 UI 中输入的名称使用属性:
# 名为 team 的项目属性将变为 team
export N8N_OTEL_TRACES_CUSTOM_ATTRIBUTE_PREFIXES='{"project":"","node":""}'
要设置自定义前缀:
# 名为 team 的项目属性将变为 acme.project.team
export N8N_OTEL_TRACES_CUSTOM_ATTRIBUTE_PREFIXES='{"project":"acme.project.","node":"acme.node."}'
要仅更改一个前缀:
# 名为 team 的项目属性将变为 acme.team
# 节点属性保留默认前缀
export N8N_OTEL_TRACES_CUSTOM_ATTRIBUTE_PREFIXES='{"project":"acme."}'
如果值不是有效 JSON、使用了其他键,或包含非字符串值,n8n 会记录警告,并对所有级别使用默认前缀。
警告
OpenTelemetry 标准属性
n8n 不会根据 OpenTelemetry 语义约定检查自定义键。如果键与 user.id 或 http.request.method 等标准属性相同,后端会将你的值作为该标准属性读取。除非你的值符合标准含义,否则请避免使用标准键。
使用 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
- 启动 n8n,开启跟踪并将其指向 Jaeger。有关设置详情,请参阅 启动 n8n:
N8N_OTEL_ENABLED=true N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 n8n start
- 运行工作流,然后在 http://localhost:16686 打开 Jaeger UI。选择“n8n”作为服务,再单击“查找跟踪”查看 n8n 发出的 OpenTelemetry 跟踪。
跨度属性
工作流和节点跨度包括以下 n8n 特定属性。
工作流程跨度 (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.project.name |
项目名称。仅限团队项目:个人项目的名称包含其所有者的姓名和电子邮箱,因此 n8n 会将其省略。从 n8n 2.44.0 起可用。 |
n8n.execution.id |
执行 ID。 |
n8n.execution.mode |
执行模式(例如,manual、webhook、trigger、retry)。 |
n8n.execution.status |
最终执行状态,包括崩溃执行的 crashed。 |
n8n.execution.is_retry |
true 如果执行是重试。 |
n8n.execution.retry_of |
当执行为重试时,原始执行 ID。 |
n8n.execution.error_type |
错误类名,执行失败时设置。崩溃时为 WorkflowCrashedError。 |
n8n.execution.crash.detector |
发现崩溃的检查:stall、queue-recovery、startup-recovery、start-failure 或 workflow-deactivation。请参阅 n8n 如何检测崩溃。从 n8n 2.42.0 开始可用。 |
n8n.execution.reconstructed |
n8n 在崩溃后重建跨度时为 true,结束原始跨度时为 false。请参阅已跟踪和重建的跨度。从 n8n 2.42.0 开始可用。 |
n8n.continuation.reason |
当工作流程在等待后恢复时在跨度链接上设置。 |
n8n.project.custom.<key> |
通过 项目级自定义跨度属性 设置的自定义属性。 |
n8n.workflow.custom.<key> |
通过 工作流级自定义跨度属性 设置的自定义属性。 |
节点跨度 (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 |
节点跨度未正常完成的原因(例如 workflow_cancelled 或 workflow_crashed)。 |
n8n.node.custom.<key> |
通过节点设置中的 节点级自定义跨度属性 或自定义节点代码中的 metadata.tracing 设置自定义属性。 |
从 n8n 2.44.0 起,节点跨度还会携带 n8n.execution.id、n8n.workflow.id、n8n.workflow.name、n8n.project.id 和 n8n.project.name,其值与工作流跨度相同。要在 Jaeger 中查找某次执行的所有跨度,请搜索标签 n8n.execution.id=<execution-id>。
当节点发生故障时,n8n 使用标准 OpenTelemetry 异常属性(exception.type、exception.message、exception.stacktrace)在跨度上记录 exception 事件。
代理运行跨度(<agent name>.generate 或 <agent name>.stream)
| 属性 | 描述 |
|---|---|
gen_ai.operation.name |
始终为 invoke_agent。 |
gen_ai.agent.name |
代理名称。 |
gen_ai.request.model |
模型 ID,已知时为 <provider>/<model name>。 |
gen_ai.conversation.id |
线程 ID。 |
gen_ai.prompt |
序列化提示、工具数量和工具目录。当 N8N_AGENTS_TRACING_RECORD_INPUTS 为 false 时省略。 |
agent_id |
代理 ID。 |
project_id |
项目 ID。 |
thread_id |
线程 ID。 |
source |
运行开始的位置(例如,workflow 或聊天集成名称)。 |
user_id |
用户 ID(如果已知)。 |
model_id |
模型 ID,已知时为 <provider>/<model name>。 |
execution_id |
执行 ID,用于工作流触发的运行。 |
workflow_id |
工作流程 ID,用于工作流程触发的运行。 |
node_id |
节点 ID,用于工作流触发的运行。 |
工具调用范围 (execute_tool <tool name>)
| 属性 | 说明 |
|---|---|
gen_ai.operation.name |
始终为 execute_tool。 |
gen_ai.tool.name |
工具名称。 |
gen_ai.tool.call.id |
工具调用 ID。 |
gen_ai.agent.name |
代理名称。 |
gen_ai.tool.call.arguments |
工具调用参数。当N8N_AGENTS_TRACING_RECORD_INPUTS为false时省略。 |
gen_ai.tool.call.result |
工具调用结果。当 N8N_AGENTS_TRACING_RECORD_OUTPUTS 为 false 时省略。 |
故障排除
您的后端没有出现任何痕迹
如果 n8n 在启动时无法到达 OTLP 端点,则会记录错误:
Failed to connect to OpenTelemetry OTLP endpoint during startup
检查:
N8N_OTEL_ENABLED设置为true。N8N_OTEL_EXPORTER_OTLP_ENDPOINT指向收集器的基础 URL(不是/v1/traces路径)。- 可从 n8n 容器或主机访问收集器。
- 设置任何所需的
N8N_OTEL_EXPORTER_OTLP_HEADERS(例如身份验证令牌)。
如果使用 grpc 协议,还要检查端点是否包含显式端口。若未指定端口,n8n 会连接到端口 443,而不是 4317。
n8n 默认情况下在 warn 级别记录 OpenTelemetry 诊断。设置 N8N_LOG_LEVEL=debug 以查看更多详细信息。
使用 gRPC 和私有 CA 时出现启动连接错误
grpc 协议的启动连接检查使用默认 TLS 信任存储,不会读取 OTEL_EXPORTER_OTLP_CERTIFICATE、OTEL_EXPORTER_OTLP_CLIENT_KEY 或 OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE,但 exporter 会使用这些变量。使用私有证书颁发机构或要求 mTLS 的收集器可能会导致检查失败并记录 Failed to connect to OpenTelemetry OTLP endpoint during startup,即使导出仍能正常工作。此检查不会阻止启动。请在 Settings 设置 > OpenTelemetry 中使用 Send test trace 发送测试跟踪 确认收集器能收到 spans。
缺少自定义跨度属性
检查:
- 您拥有企业许可证。
- 您将
N8N_OTEL_ENABLED设置为true。 - 对于节点级跨度属性,
N8N_OTEL_TRACES_INCLUDE_NODE_SPANS未设置为false。 - 如果设置了
N8N_OTEL_TRACES_CUSTOM_ATTRIBUTE_PREFIXES,请搜索新的属性键。n8n 会丢弃与内置属性同名的键。请参阅更改属性前缀。
出站请求没有 baggage 标头
请检查:
- 已在 Settings > OpenTelemetry 中启用 OpenTelemetry,或者已将
N8N_OTEL_ENABLED设置为true。 - Send outbound trace headers 已开启,并且
N8N_OTEL_TRACES_INJECT_OUTBOUND没有设置为false。 OTEL_PROPAGATORS未设置或包含baggage。- 更改
OTEL_PROPAGATORS后已重启 n8n。 - 出站调用来自使用 n8n HTTP 帮助程序的节点。自行发起原始 HTTP 调用的节点不会获得这些标头。
- 启动该执行的 webhook 请求带有
baggage标头。 - 这些条目并非全部以
n8n.为前缀。n8n 会丢弃此类条目。 - 调用方的
baggage标头在 OpenTelemetry 限制范围内。n8n 会丢弃超出限制的条目。
请参阅转发调用方 baggage。
崩溃的执行没有跨度
请在主实例上启用 OpenTelemetry。在队列模式下,由主实例检测崩溃并发出跨度,因此仅在工作线程上启用 OpenTelemetry 不会生成崩溃跨度。请在每种实例类型上设置相同的变量,以便工作线程跨度保留其父级上下文。
实例停止时正在运行的节点没有跨度。崩溃前已导出的节点跨度会保留在跟踪中。请参阅崩溃的执行。
重建的跨度显示缺少父级的警告
n8n 根据执行中存储的跟踪上下文重建跨度。该上下文是从未结束的原始跨度 ID,而 OpenTelemetry 无法重复使用跨度 ID。因此,重建的跨度会成为后端从未收到的跨度的子级,并出现此警告。该跨度带有 n8n.execution.reconstructed=true。请参阅注意事项。
工作进程跟踪缺少父上下文
在队列模式下,工作人员从数据库中读取父跟踪上下文。如果您仅在主实例上设置 OpenTelemetry 环境变量,工作线程跨度将不会链接到父工作流跟踪。在每个实例类型上设置相同的变量。
没有代理跨度出现
代理 spans 取决于 OTel 模块。检查:
N8N_OTEL_ENABLED设置为true。N8N_AGENTS_TRACING_ENABLED设置为true。
当 N8N_OTEL_ENABLED 设置为 false 时,代理仍可运行,但 n8n 不会为其发出 spans,即使 N8N_AGENTS_TRACING_ENABLED 设置为 true 也是如此。
如果使用 terraform-aws-n8n 模块在 AWS 上部署 n8n,请参阅在 AWS 上配置 Enterprise 功能。
相关资源
- 保持n8n运行
- 设置日志记录
- 监控 n8n
- 使用 Grafana 可视化指标
- 备份和恢复
- 更新n8n
- 开放式遥测
- W3C Trace Context specification 文档
- W3C Baggage 规范
- OpenTelemetry Collector documentation 文档