可观测性与稳定性 / 系统课时
使用 W3C Trace Context 传播上下文
使用 W3C Trace Context 传播上下文
这一课解决跨进程调用里“为什么 Trace 到了下游就断开”的问题:你会读懂 traceparent、理解 tracestate 的职责,并用 OpenTelemetry Propagator 完成注入与提取,让下游 Span 正确接到上游链路。
学习目标
- 读懂
traceparent中版本、Trace ID、Parent ID 与采样标志 - 理解
tracestate与 Propagator 在跨进程传播中的职责 - 能在发送端注入上下文、在接收端提取并建立远程父子关系
traceparent 到底在传什么
W3C Trace Context 把跨进程追踪所需的核心身份放进 HTTP 等载体。常见的 traceparent 形态为 version-trace-id-parent-id-trace-flags,例如:
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01这里的 32 位十六进制 trace-id 标识整条 Trace,16 位 parent-id 是发送方当前 Span 的 Span ID,最后的 01 表示采样标志包含 sampled 位。接收方不会复用这个 Span ID,而是以它作为远程父 Span,再创建自己的新 Span。
tracestate 是与 traceparent 一起传播的附加追踪状态,供不同厂商或追踪系统保存实现相关信息。它不是业务参数,也不是认证凭据;即使没有 tracestate,只要 traceparent 有效,基本父子链路仍然可以连续。

Propagator 如何完成注入与提取
Propagator 的价值是把“运行时 Context”与“传输载体”解耦。发送端调用 inject,把当前 SpanContext 序列化为载体字段;接收端调用 extract,再把字段还原成远程 Context。HTTP Header、RPC Metadata、消息属性本质上都只是不同 carrier。
下面的 Python 示例只依赖 OpenTelemetry API,先构造一个 SpanContext,再注入到字典 carrier,最后从同一 carrier 提取远程上下文:
from opentelemetry import trace
from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags, TraceState
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
source = SpanContext(
trace_id=int("4bf92f3577b34da6a3ce929d0e0e4736", 16),
span_id=int("00f067aa0ba902b7", 16),
is_remote=False,
trace_flags=TraceFlags(0x01),
trace_state=TraceState(),
)
context = trace.set_span_in_context(NonRecordingSpan(source))
carrier = {}
propagator = TraceContextTextMapPropagator()
# 发送端:把当前追踪上下文写入传输载体
propagator.inject(carrier, context=context)
print(carrier["traceparent"])
# 接收端:从载体恢复远程上下文
remote_context = propagator.extract(carrier)
remote = trace.get_current_span(remote_context).get_span_context()
print(f"{remote.trace_id:032x}")
print(f"{remote.span_id:016x}")
print(remote.is_remote)预期输出
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
4bf92f3577b34da6a3ce929d0e0e4736
00f067aa0ba902b7
True提取后的 is_remote=True 很关键,它告诉 SDK 这是来自进程外部的父上下文。真实服务中,接收端会把 remote_context 传给新建服务端 Span;新 Span 继承相同 Trace ID,但生成自己的 Span ID。
跨服务保持连续的正确顺序
一次同步调用通常按这个顺序执行:发送端先创建或激活客户端 Span,再注入当前 Context;网络层传输头字段;接收端先提取远程 Context,再创建服务端 Span。必须先 extract,再 start span,否则下游 Span 已经以本地空上下文启动,链路会被切成新的 Trace。
自动插桩通常已经替你完成这组操作。手工插桩时,不要再额外创建一套自定义 Trace ID,也不要把 SpanContext 对象直接序列化进业务 JSON;跨进程边界只传播标准 carrier 字段,运行时 Context 留在进程内部。
边界与常见错误
收到格式非法、全零 ID 或不受支持版本的 traceparent 时,应把它视为无有效远程父上下文,而不是“尽量猜”。同时,不要把 traceparent 当安全凭证:客户端可以自行构造追踪头,鉴权仍应由正式认证机制完成。
只要发送端注入的是当前 SpanContext、传输层完整保留字段、接收端在建 Span 前完成提取,同一 Trace ID 就会跨进程延续,而每个服务仍保有独立的 Span ID 与清晰的父子关系。