可观测性与稳定性 / 系统课时

使用 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,例如:

text
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

这里的 32 位十六进制 trace-id 标识整条 Trace,16 位 parent-id 是发送方当前 Span 的 Span ID,最后的 01 表示采样标志包含 sampled 位。接收方不会复用这个 Span ID,而是以它作为远程父 Span,再创建自己的新 Span。

tracestate 是与 traceparent 一起传播的附加追踪状态,供不同厂商或追踪系统保存实现相关信息。它不是业务参数,也不是认证凭据;即使没有 tracestate,只要 traceparent 有效,基本父子链路仍然可以连续。

W3C Trace Context 跨服务传播关系

Propagator 如何完成注入与提取

Propagator 的价值是把“运行时 Context”与“传输载体”解耦。发送端调用 inject,把当前 SpanContext 序列化为载体字段;接收端调用 extract,再把字段还原成远程 Context。HTTP Header、RPC Metadata、消息属性本质上都只是不同 carrier。

下面的 Python 示例只依赖 OpenTelemetry API,先构造一个 SpanContext,再注入到字典 carrier,最后从同一 carrier 提取远程上下文:

python
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)

预期输出

text
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 与清晰的父子关系。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 W3C Trace Context 传播上下文

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通