OpenTelemetry 上下文传播详解:traceparent 如何让 Trace 跨服务不断链
详解 OpenTelemetry 上下文传播、W3C traceparent 与 tracestate,以及 HTTP、gRPC 和消息队列中的父子关系与 Span Link,并说明如何检查跨服务链路。
上下文传播(Context Propagation)是指把 Trace ID、Span ID 等链路身份信息,随着请求在服务之间逐跳传递的机制——它是分布式追踪从"单点打点"变成"全链路叙事"的关键:缺少传播时,进程内的 Span 仍可关联,但跨服务的父子关系可能接不上。
核心要点速览
- SpanContext 包含 Trace ID、Span ID、TraceFlags 和 TraceState。SDK 还会标记上下文是否来自远端。Baggage 由独立的传播器处理;
- W3C Trace Context 标准用
traceparent与tracestate两个头部统一了跨厂商格式; - HTTP 走请求头、gRPC 走 Metadata、消息队列走消息属性,机制不同但目标一致;
- 下游开启了新 Trace 时,应核对上下文传播。若上下文传递正确却查不到下游 Span,还应检查采样、导出和查询范围。
上下文里到底传了什么?
分两类信息理解:
| 信息 | 内容 | 作用 |
|---|---|---|
| SpanContext | 所属 Trace ID、当前 Span ID、TraceFlags、TraceState,以及 SDK 的远端标记 | 标识当前操作,供下游建立父子关系或关联 |
| Baggage | 可选的应用键值对,例如允许传递的发布批次 | 由独立的传播器跨服务传递 |
接收端提取有效的远程上下文后,可以把新 Span 的父节点指向上游 Span,并继承 Trace ID。起止时间属于各自的 Span 记录,父 Span ID 也记录在子 Span 上。SDK 提取时设置的远端标记不占用 traceparent 字段。OpenTelemetry SpanContext API
W3C Trace Context 标准是什么?
在标准出现之前,各家厂商用私有头部(X-B3、uber-trace-id……),跨系统对接极其痛苦。W3C Trace Context 将其收敛为两个 HTTP 头部:
-
traceparent:核心身份。W3C Trace Context Level 1 的00格式是version-trace-id-parent-id-trace-flags。例如:traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01parent-id是发送方当前传播的 Span ID。Trace ID 和 parent ID 分别为 32 位、16 位小写十六进制字符,均不能全为零。trace-flags是位掩码,采样标记看最低位(0x01),置位也不保证所有 Span 最终可查。版本ff无效。对后续版本,按规范尝试读取可识别的前缀。 -
tracestate:可选、有顺序的厂商键值对列表,随有效的traceparent一起传递。
确认两端已配置兼容的传播器。支持 OTEL_PROPAGATORS 的自动配置通常默认使用 tracecontext,baggage。手动接入时,应按所用 SDK 显式配置或调用传播器。W3C Trace Context · OpenTelemetry 传播器 API
不同通信方式下如何传播?
HTTP 请求:已正确接入的客户端拦截器将当前上下文注入请求头,服务端中间件在创建服务端 Span 前提取。手动埋点也可使用传播器的注入和提取方法。
gRPC:通过 RPC Metadata 携带上下文。Metadata 走 HTTP/2 头部。检查客户端和服务端的 gRPC instrumentation 是否启用兼容的传播器。gRPC Metadata
消息队列:生产者把消息创建上下文注入消息属性(如 Kafka Header、RabbitMQ Header)。消费者提取后,按 OpenTelemetry 消息语义约定默认以 Span Link 关联消息创建上下文。一批消息可以链接到多个上下文,而一个 Span 只有一个父节点。只处理一条消息时,处理 Span 可按所用埋点方案把该消息的创建上下文用作父节点。OpenTelemetry 消息 Span 约定
自定义协议:老系统、私有 TCP 协议可提供一个由报文字段实现的载体,再用兼容的传播器注入和提取上下文。接收端提取成功后,以返回的上下文创建 Span。
传播断链的典型症状与排查
链路图在某个服务处戛然而止时,先看下游 Span 的 Trace ID 和父 Span ID。若下游建立了独立 Trace,检查上下文是否经过代理/网关、HTTP 客户端是否注入、服务端是否提取、异步代码是否传递了当前上下文。还要核对入口是否按信任边界策略重建 Trace。若 ID 对得上但后端缺少 Span,再查采样、导出和查询范围。
用一条测试请求检查传播结果
应用通过 DataKit OTLP 接收端上报后,在观测云中选一次经过多个服务的测试请求,核对同步调用的 Trace ID 和父子关系。消息处理 Span 的 Link 可在 SDK 或 Collector 导出数据中单独核对。缺少某一跳时,先回到该边界检查注入、提取和导出。
需要关联日志时,按日志关联配置写入当前请求的 trace_id 等字段,再查同一请求的日志样本。业务 Baggage 若用于检索,应由应用明确复制为允许上报的 Span 属性,并避免携带令牌或个人敏感信息。
常见问题(FAQ)
Q:所有服务必须用同一种语言的 SDK 吗? 不需要。只要大家都遵循 W3C Trace Context 格式,Java 服务传的链路 Go 服务照样能续上——这正是标准化的意义。
Q:traceparent 被网关丢掉了怎么办? 检查网关/代理配置是否透传自定义头部;内网调用可按传播要求核对头部转发规则。外部入口可按信任边界策略忽略传入上下文并创建新的 Trace。
Q:异步线程里链路断了怎么修? 手动传递上下文对象:Go 传 context.Context,Java 用 Context.wrap() 包装任务,Node.js 依赖 AsyncLocalStorage(SDK 自动处理大部分场景)。
Q:Baggage 和 Span 属性有什么区别? Baggage 由启用并执行相应传播器的调用路径传递,Span 属性随当前 Span 记录。Baggage 适合少量允许透传的业务值,不宜携带凭据、敏感数据或可用于授权的输入。按信任边界过滤对外发送的键值。W3C Baggage