OpenTelemetry 上下文传播详解：traceparent 如何让 Trace 跨服务不断链
上下文传播是分布式追踪的生命线——没有它，每个服务都是一座孤岛。本文讲清 Trace Context 与 Span Context 的构成、W3C traceparent/tracestate 标准，以及 HTTP、gRPC、消息队列三种载体下的传播机制，并说明在观测云中如何利用完整的 Trace 做跨服务下钻。
上下文传播（Context Propagation）是指把 Trace ID、Span ID 等链路身份信息，随着请求在服务之间逐跳传递的机制——它是分布式追踪从"单点打点"变成"全链路叙事"的关键：没有传播，每个 Span 都是孤儿，根本无法拼成一条完整的 Trace。
核心要点速览
- 传播的内容是两类上下文：Trace 级（Trace ID、Baggage）与 Span 级（Span ID、采样标志）；
- W3C Trace Context 标准用
traceparent与tracestate两个头部统一了跨厂商格式； - HTTP 走请求头、gRPC 走 Metadata、消息队列走消息属性，机制不同但目标一致；
- 传播一旦断链，链路就断成几截——排障时最常见的"查不到下游"多半源于此。
上下文里到底传了什么？
分两个层级理解：
| 层级 | 内容 | 作用 |
|---|---|---|
| Trace Context | Trace ID、起止时间、Baggage（可选键值对，如用户 ID、会话 ID） | 标识"这是同一次请求旅程" |
| Span Context | Span ID、所属 Trace ID、父 Span ID、采样标志 | 标识"当前操作在旅程中的位置" |
请求每经过一个服务，新的 Span 诞生，它继承 Trace ID、以调用方的 Span ID 为父——层层接力，最终在后端拼出完整调用树。
W3C Trace Context 标准是什么？
在标准出现之前，各家厂商用私有头部（X-B3、uber-trace-id……），跨系统对接极其痛苦。W3C Trace Context 将其收敛为两个 HTTP 头部：
traceparent：核心身份，格式为版本-TraceID-SpanID-标志位，例如00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01，末位01表示该链路被采样；tracestate：可选的厂商扩展信息，键值对列表，各厂商可在不破坏标准的前提下附加私有数据。
OTel 默认使用 W3C 格式传播，这也是它被称为"厂商中立"的底气之一。
不同通信方式下如何传播？
HTTP 请求：最直观——SDK 的 HTTP 客户端拦截器自动把 traceparent 注入请求头，服务端框架的中间件自动提取。绝大多数自动埋点开箱即用。
gRPC：没有 HTTP 头，但有 Metadata（本质上也是键值对）。OTel 的 gRPC 拦截器将上下文写入 Metadata，语义与 HTTP 完全一致。
消息队列：异步场景最容易断链。生产者需把上下文注入消息属性（如 Kafka Header、RabbitMQ Header），消费者取出后以"链接 Span（Link）"或父子关系续上链路。漏掉这一步，异步任务就成了链路里的黑洞。
自定义协议：老系统、私有 TCP 协议需要手动传播——从当前上下文读取 Trace ID/Span ID，塞进自定义报文字段，对端再手动恢复上下文后继续创建 Span。
传播断链的典型症状与排查
链路图在某个服务处戛然而止、下游服务的 Span 各自成了独立 Trace——基本可以断定传播断了。常见原因：经过不支持透传头部的代理/网关、使用了未埋点的 HTTP 客户端、异步代码里丢了上下文（Go 的 goroutine、Node 的回调都是重灾区）、消息队列消费端没做上下文提取。
用一条测试请求检查传播结果
应用通过 DataKit OTLP 接收端上报后，在观测云中选一次经过多个服务的测试请求，核对各 Span 是否具有相同 Trace ID 和正确的父子关系。缺少某一跳时，先回到该边界检查注入、提取和导出，而不是只扩大查询时间。
需要关联日志时，按日志关联配置写入当前请求的 trace_id 等字段，再查同一请求的日志样本。业务 Baggage 若用于检索，应由应用明确复制为允许上报的 Span 属性，并避免携带令牌或个人敏感信息。
常见问题（FAQ）
Q：所有服务必须用同一种语言的 SDK 吗？ 不需要。只要大家都遵循 W3C Trace Context 格式，Java 服务传的链路 Go 服务照样能续上——这正是标准化的意义。
Q：traceparent 被网关丢掉了怎么办？ 检查网关/代理配置是否透传自定义头部；Nginx、Envoy 等主流网关默认透传，但某些安全策略会清洗未知头部，需加白名单。
Q：异步线程里链路断了怎么修？ 手动传递上下文对象：Go 传 context.Context，Java 用 Context.wrap() 包装任务，Node.js 依赖 AsyncLocalStorage（SDK 自动处理大部分场景）。
Q：Baggage 和 Span 属性有什么区别？ Baggage 会随请求传播到下游所有服务，Span 属性只属于当前 Span。Baggage 适合少量贯穿全链路的业务标识，切勿塞大对象——它会出现在每个请求的头部里。
