traceparent 解码器 — W3C Trace Context

什么是 traceparent 请求头？

# The header as it travels on the wire
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate:  rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

# Read the four fields apart
#   version     00
#   trace-id    4bf92f3577b34da6a3ce929d0e0e4736   (16 bytes, whole request)
#   parent-id   00f067aa0ba902b7                   (8 bytes, calling span)
#   trace-flags 01                                 (bit 0 set = sampled)

# Send one yourself
$ curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
       https://example.com/api

核心功能

traceparent 示例解码

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

version 00 · trace-id 4bf92f3577b34da6a3ce929d0e0e4736 · parent-id 00f067aa0ba902b7 · trace-flags 01 (sampled)

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00

有效 header · sampled 位为 0

00-00000000000000000000000000000000-00f067aa0ba902b7-01

无效 —— trace-id 全为 0

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

x-datadog-trace-id 11803532876627986230 · _dd.p.tid 4bf92f3577b34da6

如何使用 traceparent 解码器

1. 1

   粘贴 traceparent 请求头

   直接放入原始的请求头值，例如 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01。解码随输入进行，不需要按任何按钮。

2. 2

   分开读四个字段

   version、trace-id、parent-id 和 trace-flags 各占一行，每行都带复制按钮，你可以只把 trace ID 拿去查询，而不用手动选中 32 个字符。

3. 3

   逐位检查标志位

   trace-flags 字节被展开成全部 8 个位并标出掩码，sampled 和 Level 2 的 random-trace-id 标志都单独可见，不再藏在一个两字符的值里。

4. 4

   转换成后端要的格式

   下方会生成 Datadog、AWS X-Ray 以及 B3 的两种形式，包括 Datadog 需要的低 64 位十进制 trace ID，和随它一起传递的高 64 位标签。

5. 5

   加上 tracestate 并分享结果

   粘贴 tracestate 请求头即可逐条列出成员、单独校验，并对照 32 个成员的上限计数；然后用复制链接把当前状态原样装进一个 URL，丢进工单里。

traceparent 常见错误

if (traceFlags === 0x01) { record(); }

if (traceFlags & 0x01) { record(); }

x-datadog-trace-id: 100985939111033328018442752961257817910

x-datadog-trace-id: 11803532876627986230
x-datadog-tags: _dd.p.tid=4bf92f3577b34da6

if (version !== '00') throw new Error('bad traceparent');

if (version !== '00' && header.length >= 55) { /* parse the known prefix */ }

traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

traceparent 解码器能帮你做什么

弄清一条链路为什么没有 span

粘贴进来的请求头，读它的 sampled 位。如果是 0，这条链路本来就不会被记录，答案在调用方那边，不在你的埋点上——分清这一点，能省下大量核查自家采样配置的时间。

找到后端查不到的那条链路

从应用日志里复制出来的 trace ID 在 Datadog 里查不到，通常是格式的问题。在这里转换一下，就能看到 API 期望的低 64 位十进制标识符，以及必须随它一起提供的高 64 位标签。

验证网关注入的请求头

代理和服务网格会在入口处生成追踪上下文。把实际收到的内容粘进来，先确认长度、小写十六进制和非零标识符，再去假设问题出在下游。

手工复现一条生产链路

拿一个真实请求的请求头，对预发环境的端点重放，跟着同一条链路走一遍。用 curl 命令生成器构造请求，把请求头直接粘进去即可。

向团队讲清楚 trace context

本页的字段解剖表和 trace-flags 表是可以直接指着讲的静态参考资料，预设按钮则能演示每一种失败形态，不必真的把哪个服务弄坏来制造现场。

W3C Trace Context 校验器的工作原理

四字段语法

version "-" trace-id "-" parent-id "-" trace-flags，全部为小写十六进制。version 2 位，trace-id 32 位，parent-id 16 位，trace-flags 2 位——52 个十六进制字符加 3 个连字符，version 00 下恰好 55 个字符。大写十六进制会让请求头非法，哪怕值本身看着没错；而全零的 trace-id 和全零的 parent-id 都是明确非法，而不是「为空」。

trace-flags 是位字段

位 0（掩码 0x01）是 sampled：置起表示调用方可能记录了追踪数据。位 1（掩码 0x02）由 Level 2 引入，是 random-trace-id：置起时，trace-id 至少最右侧 7 字节必须是均匀分布地随机选出的，下游系统因此可以基于它们采样或分片。位 2 到位 7 保留，接收时必须忽略，向外发请求时必须清零。正因为保留位可能出现，这个字段必须用按位与来判断——拿它和 0x01 做相等比较，会把一条同时带有保留位的已采样链路误报掉。

对未来版本的前向兼容

version 今天是 00，ff 被禁止，但一个把其他值一律拒绝的解析器是错的。规范要求接收方在版本更高、且请求头长度不短于已知格式时尝试解析，读出自己认识的字段并容忍多余的尾部数据，而不是重新开一条链路。本解码器遵循这条规则：更高的版本能解析成功，并被标记为警告而不是错误。

生产中真会咬人的 tracestate 限制

最多 32 个 list-member——这是一条硬性的语法边界，列表更长时整个 header 就是非法的，接收方会直接丢弃。每个键最长 256 个字符，以小写字母或数字开头；从 Level 2 起，@ 只是一个普通的键字符，不再是租户分隔符。每个值是 1 到 256 个可打印 ASCII 字符，不能含逗号或等号。重复的键非法；而空的 list-member 是规范明确允许的——中间件删掉某个条目后留下的尾随逗号，仍然是一个合法的 header。另有一条独立的约定：厂商应当传播至少 512 个字符的合并后 header；当需要裁剪以塞进这个预算时，应当先丢掉超过 128 个字符的条目——所以话多的厂商，数据总比话少的先消失。

Trace Context 最佳实践

用按位与来判断标志位

写 flags & 0x01，不要写 flags == 0x01。8 个位里有 6 个留给未来使用，只要其中任何一个开始出现在真实流量里，相等比较就会开始误报已采样的链路。

把全零 ID 当成管道坏了

它不是一个可以容忍的空值。拒绝这个请求头，然后去找那个没能初始化 tracer、或者在注入占位值的组件。

sampled 位为 0 时往上游看

基于父级的采样器会传播调用方的决定。如果链路缺失，先找出是哪个服务带着关掉采样的 parent span 在调你，再去审查自己的配置。

让 tracestate 保持简短

32 个成员的上限是一条硬性的语法边界——一旦超出，整个 header 就是非法的。另外，合并后的 header 只有 512 个字符能保证被传播，裁剪时会先丢掉超过 128 个字符的条目。任何你希望能撑过一条长调用链的数据，都不该放在 tracestate 里。

永远不要把 trace ID 当成 JavaScript number 打日志

128 位的 trace ID，乃至 64 位的 Datadog 标识符，都超过了 Number.MAX_SAFE_INTEGER。把它们当字符串保存，需要做运算时用 BigInt 转换，否则末尾几位会被悄悄改掉。

traceparent 解码器常见问题