📚 课程目录第4章上下文传播机制

上下文传播机制：HTTP Header、W3C Trace Context、gRPC Metadata

链路追踪里有个核心问题——你是怎么把 trace_id 和 span_id 从一个服务传到下一个服务的？

我刚开始做分布式追踪时，以为只要在代码里生成一个 ID，下游自然就能拿到。结果第一次联调就懵了：服务 B 拿到的是 null，服务 C 直接报错。后来才发现，上下文传播这事，得靠协议层面的「信使」来背。

说白了，每个请求从上游到下游，得把追踪上下文塞进通信协议的某个「口袋」里。常见的口袋就三个：HTTP Header、W3C Trace Context 标准、gRPC Metadata。咱们一个一个拆开看。

HTTP Header 手动传播

这是最原始的方法。我在第一个线上项目里就是这么干的——在 HTTP 请求头里自定义两个字段：X-Trace-Id 和 X-Span-Id。

个人经验： 手动 Header 传播最容易踩坑。我曾经因为拼写错误（X-Trace-Id 写成了 X-Trace-Idd），排查了整整一个下午。嗯，后来就改用标准了。

代码示例一般长这样：

// 上游服务发送请求
String traceId = currentSpan.getTraceId();
String spanId = currentSpan.getSpanId();
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("X-Trace-Id", traceId);
conn.setRequestProperty("X-Span-Id", spanId);

// 下游服务接收
String traceId = request.getHeader("X-Trace-Id");
String spanId = request.getHeader("X-Span-Id");
Span newSpan = tracer.buildSpan("service-b-process")
        .addReference(References.CHILD_OF, 
            new SpanContext(traceId, spanId, ...))
        .start();

注意几个坑：

Header 名称大小写？HTTP 规范里 Header 名不区分大小写，但某些代理（比如 Nginx）可能会改掉下划线。我记得有次客户端的 X_Client_Id 被 Nginx 直接丢弃了，因为默认配置会过滤带下划线的 Header。解决方案是用 X-Client-Id 这种短横线格式。
透传哪些字段？光传 trace_id 和 span_id 不够，还得传采样标记、baggage 等。手动维护容易漏。
多语言 SDK 兼容？Java 里用 HttpURLConnection，Go 里用 http.Request.Header，Node.js 用 req.headers——每个语言都得写一遍解析逻辑。

避坑提醒： 千万不要在 Header 里放二进制数据或者超大字符串。有一次我看到有人把整个 Span 对象序列化成 JSON 塞进 Header，结果请求头超过 8KB，直接被网关拦截了。

W3C Trace Context 标准

手动传播太乱了，所以 W3C 在 2019 年推出了 Trace Context 标准。现在我用的大部分 SDK 都已经内置支持。标准定义了三个 Header：

Header 名称	格式	说明
`traceparent`	`00-{trace_id}-{parent_span_id}-{trace_flags}`	必须携带，核心字段
`tracestate`	`vendor1=value1,vendor2=value2`	可选，用于传递厂商特定数据

traceparent 字符串一共 55 个字符，结构清晰：

00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
│  └──────────trace_id─────────────┘─└───parent_span_id───┘─flags
version=00
trace_id=0af7651916cd43dd8448eb211c80319c (16字节，32个十六进制字符)
parent_span_id=b7ad6b7169203331 (8字节，16个十六进制字符)
trace_flags=01 (表示采样)

为啥我喜欢这个标准？ 因为所有主流追踪系统（Jaeger、Zipkin、OpenTelemetry）都认它。你不再需要关心上游用的是什么 SDK，只要双方都遵守 traceparent，上下文就能自动传下去。

你想想看，一个请求从 Java 服务 -> Python 服务 -> Go 服务，中间经过 API 网关、消息队列、Kubernetes Sidecar——如果没有标准，每个中间件都得手动透传自定义 Header，那得多痛苦。

最佳实践： 从 2023 年开始，我所有新项目的链路追踪都只用 W3C Trace Context。SDK 自动注入 traceparent，你几乎不用写任何传播代码。除非你还在用特别老的追踪框架，否则别折腾手动 Header 了。

但 tracestate 有个容易忽略的细节——它的值总长度不能超过 512 字节。我在一个 SaaS 项目里遇到过，某个厂商的 baggage 内容特别大（存了用户登录 IP、设备指纹等），导致 tracestate 被截断，下游解析出错了。解决办法是用短键名，或者把大数据放到请求体里。

gRPC Metadata 传播

如果你的服务间用 gRPC 通信，那就用 Metadata。gRPC 的 Metadata 本质上就是 HTTP/2 的 Header，只不过 API 更友好。

我记得第一次接触 gRPC 链路追踪时，以为要自己写拦截器。后来才发现，大部分 gRPC 客户端库（如 Java 的 grpc-java、Go 的 google.golang.org/grpc）都提供了拦截器自动注入追踪上下文。

// Java gRPC 客户端（使用 OpenTelemetry）
ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 50051)
    .intercept(OpenTelemetryClientInterceptor.create(openTelemetry))
    .build();

// Go gRPC 客户端
conn, _ := grpc.Dial("localhost:50051",
    grpc.WithUnaryInterceptor(otelgrpc.UnaryClientInterceptor()))
// 服务端
grpcServer := grpc.NewServer(
    grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()))

Metadata 跟 HTTP Header 的区别？

gRPC Metadata 支持二进制值（通过 Base64 编码），而 HTTP Header 原则上只支持 ASCII。
Metadata 的 key 通常以小写 + 短横线命名，如 traceparent（跟 W3C 一致）。
gRPC 拦截器机制让你在代码层面几乎看不见上下文传播——只要配置好，所有 RPC 调用自动携带 traceparent。

小心二进制 baggage： 虽然 gRPC Metadata 支持二进制，但我建议不要真的往里塞太多二进制数据。gRPC 底层是 HTTP/2，头部压缩（HPACK）对二进制数据效率很低。我曾经见过把 protobuf 序列化后的 entity 直接存进 Metadata，结果每个请求的头部膨胀到几 KB，完全抵消了 gRPC 的高性能优势。

三种传播方式对比

下面这张图可以帮你快速定位该用哪种方案：

从图里能看出，推荐路径是：只要你的技术栈支持，优先走 W3C Trace Context。gRPC 场景用它本身的 Metadata 结合 W3C 的 traceparent 字段，实际上也是标准化的。

我的选择策略： 如果服务间全是 RESTful HTTP，直接用 W3C。如果混合了 gRPC 和 HTTP，那就统一使用 W3C 标准——因为 gRPC Metadata 里也能放 traceparent，两边互通无压力。只有遇到特别老的系统（比如某银行核心还在用 SOAP），才考虑手动 Header + 自定义转换逻辑。

最后再说个常见场景：**异步消息队列（Kafka/RabbitMQ）**。这种场景下没有 HTTP Header 或 gRPC Metadata，通常用消息的 Header 或 Properties 字段来携带 traceparent。我个人习惯是把 traceparent 作为消息的一个 key-value 属性传入，消费者端再用一个拦截器读取并创建 Span。注意序列化问题——某些消息队列的属性值只支持字符串，二进制 baggage 别往里塞。

好，上下文传播机制就聊到这儿。记住三条：能标准化就别手动，能自动注入就别手动写代码，能保守长度就别塞大数据。你在项目里遇到传播问题，先检查 traceparent 有没有被中间件切掉或者覆盖，90% 的故障都出在这个环节。