Skip to content

OpenTelemetry 跟踪(OpenTelemetry tracing)#

此功能仍在开发中——最初从版本 2.19.0 开始提供

代理遥测和开放遥测格式的指标将很快推出

n8n 可以为工作流和节点执行发出 OpenTelemetry 跟踪。使用这些跟踪来监控执行延迟、调试失败，并在你的可观测性堆栈中跟踪跨服务的请求。

🌐 n8n can emit OpenTelemetry traces for workflow and node executions. Use these traces to monitor execution latency, debug failures, and track requests across services in your observability stack.

功能可用性

OpenTelemetry 工作流追踪要求设置环境变量，因此仅在自托管的 n8n 上可用。

你得到的(What you get)#

当你开启追踪时，n8n 会为每次执行导出两种类型的跨度：

🌐 When you turn on tracing, n8n exports two kinds of spans for each execution:

  • workflow.execute：每次工作流执行一个跨度。它记录工作流 ID、名称、版本、节点数量、执行模式、状态以及任何错误类型。
  • node.execute：每个节点执行一个跨度，嵌套在其工作流跨度内。它记录节点 ID、名称、类型、版本，以及输入和输出项的数量。

每个跨度都包括标识 n8n 实例的资源属性：

🌐 Each span includes resource attributes that identify the n8n instance:

  • service.name（默认值 n8n）
  • service.version（n8n 版本）
  • n8n.instance.id
  • n8n.instance.role（例如，main、worker或webhook）

n8n 也处理跟踪上下文传播：

🌐 n8n also handles trace context propagation:

  • 入站：如果 webhook 请求包含一个 W3C traceparent 头，n8n 会将其用作工作流跨度的父级。这会将 n8n 工作流跟踪链接到上游调用方。
  • 出站：HTTP 请求节点（以及其他使用 n8n HTTP 辅助工具的节点）可以在出站请求中注入 traceparent 头。支持 W3C 跟踪上下文的下游服务因此可以继续跟踪。
  • 子工作流：子工作流的跨度使用父工作流的跨度作为其父跨度。
  • 恢复的工作流：当工作流在等待后恢复时，新的跨度会通过跨度链接回到前一个跨度。

启用跟踪(Enable tracing)#

在你希望启用工作流跟踪的每个 n8n 实例上设置以下环境变量（主节点、工作节点和 webhook 处理器）：

🌐 Set the following environment variables on each n8n instance you want workflow tracing enabled (main, workers, and webhook processors):

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

重启 n8n。该实例开始使用 Protobuf 编码通过 OTLP HTTP 导出跨度。

🌐 Restart n8n. The instance starts exporting spans over OTLP HTTP using the Protobuf encoding.

n8n 默认会在端点附加 /v1/traces。将 N8N_OTEL_EXPORTER_OTLP_ENDPOINT 指向收集器的基础 URL，而不是跟踪路径。

🌐 n8n appends /v1/traces to the endpoint by default. Point N8N_OTEL_EXPORTER_OTLP_ENDPOINT at the base URL of your collector, not the traces path.

如果你的收集器需要身份验证，请将 N8N_OTEL_EXPORTER_OTLP_HEADERS 设置为由逗号分隔的 key=value 对列表：

🌐 If your collector needs authentication, set N8N_OTEL_EXPORTER_OTLP_HEADERS to a comma-separated list of key=value pairs:

1
2
3
4
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 环境变量。

🌐 For the full list of supported variables, refer to OpenTelemetry environment variables.

排队模式

在队列模式下，在主实例、工作实例和 webhook 实例上设置 OpenTelemetry 变量。跟踪上下文在主实例、工作实例和 webhook 实例之间传播。

采样(Sampling)#

默认情况下，n8n 会导出每个跟踪。要在繁忙的实例中减少数据量，请将 N8N_OTEL_TRACES_SAMPLE_RATE 设置为介于 0 和 1 之间的值：

🌐 By default, n8n exports every trace. To reduce volume in busy instances, set N8N_OTEL_TRACES_SAMPLE_RATE to a value between 0 and 1:

1
2
# Export 10% of traces
export N8N_OTEL_TRACES_SAMPLE_RATE=0.1

n8n 使用跟踪 ID 比例采样器，因此相同的跟踪 ID 会在跟踪中的所有跨度中全部采样或全部丢弃。

🌐 n8n uses a trace ID ratio sampler, so the same trace ID is either fully sampled or fully dropped across all spans in the trace.

n8n 将为每次工作流执行输出跟踪——这包括已发布的工作流、未发布的工作流和测试执行——在未来的版本中，将提供一个切换选项来仅跟踪已发布的工作流

减少跨度体积(Reduce span volume)#

工作流中的每个节点都会生成其自己的跨度。对于拥有大量节点的工作流，这可能会产生比你需要的更多的数据。要仅导出工作流级别的跨度，请设置：

🌐 Each node in a workflow produces its own span. For workflows with lots of nodes, this can produce more data than you need. To export only workflow-level spans, set:

1
export N8N_OTEL_TRACES_INCLUDE_NODE_SPANS=false

要阻止 n8n 在外发 HTTP 请求中注入 traceparent 头，请设置：

🌐 To stop n8n from injecting traceparent headers into outbound HTTP requests, set:

1
export N8N_OTEL_TRACES_INJECT_OUTBOUND=false

向节点跨度添加自定义属性(Add custom attributes to node spans)#

如果你正在构建自定义节点，你可以将自定义键值对附加到节点的跨度上。在节点的execute方法中调用setMetadata：

🌐 If you're building a custom node, you can attach custom key-value pairs to the node's span. Call setMetadata from the node's execute method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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.。值必须是字符串、数字或布尔值。

🌐 n8n prefixes each key with n8n.node.custom. on the exported span. Values must be strings, numbers, or boolean.

此 API 无法从代码节点使用。它旨在供希望用特定字段的数据丰富跨度的节点作者使用。

🌐 This API isn't available from the Code node. It's intended for node authors who want to enrich spans with domain-specific data.

试试 Jaeger(Try it out with Jaeger)#

你可以将追踪发送到本地的 [Jaeger]（https://www.jaegertracing.io/）{：target=“_blank” .external-link} 实例，查看它们的实际操作。

🌐 You can send traces to a local Jaeger instance to see them in action.

  1. 将以下内容保存为 docker-compose.yml：
1
2
3
4
5
6
7
services:
  jaeger:
    image: jaegertracing/jaeger:latest
    ports:
      - "16686:16686" # UI
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
  1. 启动 Jaeger：
1
docker compose up -d
  1. 启动 n8n 并开启追踪，同时指向 Jaeger。有关启动 n8n的信息可以在本手册的其他地方找到：
1
N8N_OTEL_ENABLED=true N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 n8n start
  1. 运行一个工作流，然后在 http://localhost:16686 打开 Jaeger UI - 选择服务 “n8n”，然后点击 “Find traces” 查看 n8n 发出的 OpenTelemetry 跟踪。

跨度属性(Span attributes)#

工作流和节点范围包括以下 n8n 特有的属性。

🌐 Workflow and node spans include the following n8n-specific attributes.

工作流跨度（workflow.execute）(Workflow 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 工作流在等待后恢复时在跨度链接上设置

节点跨度 (node.execute)(Node 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 节点跨度未正常完成的原因（例如，workflow_cancelled）。
n8n.node.custom.<key> 通过节点输出中的 metadata.tracing 设置的自定义属性。

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

🌐 When a node fails, n8n records an exception event on the span with the standard OpenTelemetry exception attributes (exception.type, exception.message, exception.stacktrace).

故障排除(Troubleshooting)#

在你的后端没有出现任何痕迹(No traces appear in your backend)#

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

🌐 If n8n can't reach the OTLP endpoint at startup, it logs an error:

1
Failed to connect to OpenTelemetry OTLP endpoint during startup

检查以下内容：

🌐 Check that:

  • N8N_OTEL_ENABLED 设置为 true。
  • N8N_OTEL_EXPORTER_OTLP_ENDPOINT 指向收集器的基础 URL（而不是 /v1/traces 路径）。
  • 收集器可以从 n8n 容器或主机访问。
  • 任何必需的 N8N_OTEL_EXPORTER_OTLP_HEADERS（例如身份验证令牌）已设置。

n8n 默认以 warn 级别记录 OpenTelemetry 诊断信息。设置 N8N_LOG_LEVEL=debug 可查看更多详细信息。

🌐 n8n logs OpenTelemetry diagnostics at warn level by default. Set N8N_LOG_LEVEL=debug to see more detail.

工作线程追踪缺少父上下文(Worker traces are missing parent context)#

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

🌐 In queue mode, workers read the parent trace context from the database. If you only set the OpenTelemetry environment variables on the main instance, worker spans won't link to the parent workflow trace. Set the same variables on every instance type.