首页/云/可观测性速查/W3C Trace Context:跨服务传播标准

W3C Trace Context:跨服务传播标准

traceparent 头承载 trace_id、parent span_id 与采样标志,tracestate 携带厂商额外状态;是跨语言跨厂商链路能连起来的关键标准。

可观测性速查云更新于 2026-10-13

跨服务为什么需要标准

跨服务的链路能连起来,靠的是上下文传播标准:上游把链路标识与当前环节标识放进请求头,下游读取后创建子环节并继续传递。没有统一标准时,不同语言与厂商的实现互不兼容,链路会在服务边界断开。

两个请求头

标准定义了两个头:主头承载版本、链路标识、当前环节标识与标志位,附带头承载厂商的额外状态。主头格式固定,接收方校验格式与版本后继续传递;附带头则需保持键值顺序,避免破坏其他厂商写入的条目。

基本信息

主头字段版本、链路标识、环节标识与标志位,用短横线分隔
标识长度链路标识三十二位十六进制,环节标识十六位
标志位最低位表示是否采样
附带头承载厂商额外状态,需保持键值顺序

典型使用场景

  • 跨语言调用:不同技术栈的服务共享同一条链路
  • 网关透传:确保网关不丢弃链路请求头
  • 异步消息传递:把上下文随消息一起投递
  • 多厂商共存:用附带头承载各家的额外状态
  • 统一采集:下游按同一字段解析链路标识

主头格式

主头格式
# 版本-链路标识-环节标识-标志位
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
#             |  |                                |                |
#             |  链路标识(32 位)                环节标识(16 位) 标志位
tracestate: vendor=value

字段读法

字段含义取值
版本协议版本当前为 00
链路标识整条链路的唯一标识三十二位十六进制
环节标识当前环节的标识十六位十六进制
标志位采样等标志最低位表示是否采样

接入时的检查

  • 逐个组件验证透传:网关、代理与消息中间件都可能丢弃请求头
  • 统一解析实现:各语言使用标准库而不是自行解析
  • 用一次真实跨服务调用验证上下游能否连成一条完整链路
接收方应校验格式与版本后再继续传递:格式非法时应忽略该请求头,而不是原样透传导致下游解析失败。
用自定义请求头代替标准头会让链路无法与生态互通:跨厂商工具与第三方组件都不识别这些私有字段。

易错点

  • 网关或代理丢弃请求头:链路断在服务边界,故障时最需要的一段恰好缺失
  • 使用自定义标识头:无法与生态系统中的其他组件互通
  • 随处覆盖附带头:破坏其他厂商写入的状态,跨厂商链路出现异常
  • 标识生成不唯一:不同请求被串成一条链路,排查结论完全错乱

数据来源与参考

  • W3C Trace Context Recommendation
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌