n8n 中文文档

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.id
  • n8n.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 处理器之间重新加载它们。

要配置跟踪:

  1. 选择 设置 > OpenTelemetry。
  2. 打开启用 OpenTelemetry。
  3. 在 收集器连接 下,输入您的 OTLP 端点 和任何其他连接详细信息。
  4. 在跟踪下,设置采样和跨度选项。
  5. 选择保存设置。

要检查 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>

添加项目跨度属性

要添加项目级跨度属性:

  1. 打开一个项目。
  2. 选择项目设置。
  3. 在“自定义跨度属性”下,添加一个或多个跨度属性。
  4. 选择保存。

使用纯文本作为项目属性值。

添加工作流跨度属性

要添加工作流级别跨度属性:

  1. 打开工作流程。
  2. 打开工作流程设置。
  3. 在“自定义跨度属性”下,选择“配置”。
  4. 添加一个或多个跨度属性。
  5. 选择保存。

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

添加节点跨度属性

添加节点级跨度属性:

  1. 打开节点并选择 设置 选项卡。
  2. 在“自定义跨度属性”下,选择“添加属性”。
  3. 输入密钥。密钥必须是纯文本。
  4. 输入值。值可以是纯文本或表达式,例如 ={{ $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 实例以查看效果。

  1. 将以下内容另存为 docker-compose.yml:
services:
  jaeger:
    image: jaegertracing/jaeger:latest
    ports:
      - "16686:16686" # UI
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
  1. 启动 Jaeger:
docker compose up -d
  1. 启动 n8n,开启跟踪并将其指向 Jaeger。有关设置详情,请参阅 启动 n8n:
N8N_OTEL_ENABLED=true N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 n8n start
  1. 运行工作流,然后在 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?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。