第 3 章 链路追踪数据模型与标准：OpenTelemetry 协议与 W3C Trace Context 规范

说到分布式链路追踪，刚接触的同事常问我一个问题：那么多家公司的追踪系统，SkyWalking、Jaeger、Zipkin，各自的数据格式都不一样，怎么打通？

这个问题问到了根子上。早期链路追踪的痛点，说白了就是「各家自扫门前雪」。你用了 Zipkin 的 SDK，想接入 Jaeger 的后端？基本没戏。直到社区推出了两个关键标准——W3C Trace Context 和 OpenTelemetry，数据墙才算真正推倒。

我个人习惯把这两个标准的关系理解为「交通规则与汽车制造」：

• W3C Trace Context 定义的是请求经过每个路口时，要在车身上喷什么编号（traceId、spanId）。它只管标识怎么传，不管数据长什么样。
• OpenTelemetry 定义的是整辆车的制造标准——引擎盖下有哪些信号（Span、Log、Metric），信号内部的数据结构长啥样。它还顺手给你生产了一套标准零件库（SDK/API）。

你想想看，一个请求经过几十个服务，如果没有统一的 traceId 格式，能串起来吗？连串都串不起来，故障排查就是天方夜谭。这一章我们就来把这套标准彻底掰开揉碎。

3.1 W3C Trace Context：请求身份证的标准化

W3C Trace Context 的核心贡献是定义了三个 HTTP 头字段。我在项目中遇到过多次因 traceId 格式不统一导致的追踪断裂，后来全公司统一接入这套规范后，问题直接清零。

traceparent 是最核心的。它的格式固定为：

• 版本号：目前是 00，占 2 个十六进制字符。
• trace-id：全局唯一的调用链 ID，16 字节、32 个十六进制字符。我见过有人用 UUID 截断，这会导致碰撞，不建议。
• span-id：当前调用单元的 ID，8 字节、16 个十六进制字符。
• trace-flags：目前只定义了最低位为采样标记（1=采样，0=不采样）。

// traceparent 字段格式
00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
|  |______________________________|__________________|  |
|          trace-id                      span-id      flags
version

3.2 OpenTelemetry 数据模型：从信号到结构

W3C 只解决了请求怎么串的问题，而 OpenTelemetry 要回答的是：串起来之后，每一条记录到底长什么样。我建议你在学习数据模型时，先看 Span，因为它是一切的基础。

3.2.1 Span：追踪的最小原子

一个 Span 代表分布式系统中一个独立的工作单元。你可以把它想象成一次方法调用、一次数据库查询、或一条消息的发送。Span 的结构包含以下核心字段：

• TraceId：所属的完整链路 ID。
• SpanId：自身 ID。
• ParentSpanId：父 Span 的 ID。根 Span 此字段为空。
• Name：操作名称，如 HTTP GET /api/users。
• Kind：Span 角色 — SERVER、CLIENT、PRODUCER、CONSUMER、INTERNAL。
• StartTime / EndTime：时间戳，用于计算延迟。
• Status：Unset、Ok、Error。
• Attributes：键值对，附加业务或技术元数据。
• Events：时间戳+事件名，用于记录关键事件（如异常、SQL 慢日志）。
• Links：关联到其他 Span，常用于异步消息场景。

3.2.2 Resource 与 InstrumentationScope

除了 Span 本身，OpenTelemetry 还定义了两种重要的元数据结构：

为什么要分离这两个？我记得有一次排查一个奇怪的问题：某服务的调用链中，所有数据库 Span 都缺少 SQL 语句。后来发现是 JDBC 插件版本太低，没有正确设置 Attributes。Resource 让服务维度归因成为可能，InstrumentationScope 让插件版本梯度变得可审计。

3.2.3 Span 的传播机制

Span 在进程间是怎么传的？本质上就是通过 W3C Trace Context 头。当你收到一个 HTTP 请求，先解析 traceparent，从里面拿到 parentSpanId，然后创建新的 Span，把 parentSpanId 填进去。处理完成后再把当前 SpanId 写入响应头，传给下游。

// 简化的 Span 创建逻辑（伪代码）
Span currentSpan = tracer.spanBuilder("GET /order")
    .setParent(extractFromHttpHeaders(request))  // 从 traceparent 提取父 Span
    .setSpanKind(SpanKind.SERVER)
    .startSpan();

currentSpan.setAttribute("http.method", "GET");
currentSpan.setAttribute("http.url", request.getRequestURI());

try {
    // 执行业务逻辑
    ...
} catch (Exception e) {
    currentSpan.setStatus(StatusCode.ERROR);
    currentSpan.recordException(e);
} finally {
    currentSpan.end();
}

3.3 标准全景关系图

下面这张图把 W3C Trace Context、OpenTelemetry 协议以及数据流的关系串了起来。你看看就明白了。

3.4 实战中你一定要知道的三个坑

标准说起来简单，落地时全是细节。我把这些年踩过的坑总结一下：

1. traceparent 的 truncation（截断）问题：前面讲过了，我建议在 SDK 层做严格校验。trace-id 必须是 32 位 hex，多一位少一位都直接拒绝。

2. spanKind 设置错误：很多人都把 SPAN_KIND_SERVER 和 SPAN_KIND_CLIENT 搞反。我记得排查过一个调用链，所有“收到请求”的 Span 都被标成了 CLIENT，结果依赖拓扑图全部画反了。原则只有一个：在接收方视角用 SERVER，发起方视角用 CLIENT。

3. tracestate 的滥用：有的团队把 tracestate 当成全局 key-value 缓存，往里丢大段业务数据。但 W3C 规定 tracestate 应该控制在几十字节以内。我曾经见过一个极端案例，tracestate 塞了 8KB 的 JSON，导致 HTTP 头超长被 Nginx 拒绝。业务上下文应该用 baggage 或者在 Span Attributes 里记录。