4. W3C TraceContext 标准：traceparent 与 tracestate 头格式、传播规则

在分布式追踪与可观测性体系中，W3C TraceContext 是跨服务、跨组件传递追踪上下文的行业标准。它定义了两个 HTTP 头：traceparent 和 tracestate，分别承载追踪标识与供应商扩展信息。在自助目录的配置同步场景中，Collector 管道必须严格遵循该标准，才能确保从配置变更请求到最终同步确认的完整链路可追溯。

4.1 traceparent 头：核心追踪标识

traceparent 是 TraceContext 的必选头，采用固定 55 字节的 dash-hex 格式，由三个字段组成：

格式示例：

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

其中：

• 00 — 版本号
• 0af7651916cd43dd8448eb211c80319c — TraceId
• b7ad6b7169203331 — SpanId
• 01 — 采样标记（01 表示记录并采样）

4.2 tracestate 头：供应商扩展与传播规则

tracestate 是可选头，用于携带与 traceparent 关联的供应商特定数据。其格式为逗号分隔的键值对列表，每个键值对由 = 连接：

tracestate: vendor1=value1,vendor2=value2

关键传播规则：

• 保留顺序： 列表项从左到右按优先级排列，最左侧为最高优先级。
• 透传不变： 服务不应修改其他供应商的键值对，除非明确需要更新。
• 长度限制： 整个 tracestate 头不得超过 512 字节。
• 采样一致性： 若 traceparent 标记为采样，tracestate 中的供应商数据也应保持一致。

4.3 传播规则与 Collector 管道集成

W3C TraceContext 的传播规则定义了如何在服务间传递这两个头。在 Collector 管道中，传播行为必须遵循以下原则：

4.4 上下文传播流程示意图

下图展示了在自助目录配置同步场景中，W3C TraceContext 头如何通过 Collector 管道的各个阶段进行传播：

4.5 配置同步中的实际应用案例

假设自助目录收到一个配置变更请求：更新租户 A 的 LDAP 连接字符串。Collector 管道中的上下文传播过程如下：

1. 入口（API 网关）： 生成 TraceId abc123...，SpanId span001，设置采样标记 01。
2. Receiver（HTTP 接收器）： 提取 traceparent，创建子 Span（SpanId span002），记录请求方法、路径。
3. Processor（验证处理器）： 转发时保持 TraceId，生成 SpanId span003，在 tracestate 中追加 tenant=A。
4. Exporter（同步导出器）： 注入完整的 traceparent 和 tracestate 到目标系统（如 LDAP 服务器）的请求头中。

4.6 与 OpenTelemetry 的兼容性

W3C TraceContext 是 OpenTelemetry 默认的上下文传播协议。在 Collector 管道中，通过配置 propagators 选项启用：

receivers:
  otlp:
    protocols:
      grpc:
        propagators: [tracecontext]   # 启用 W3C TraceContext 传播

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  otlp:
    endpoint: "otel-collector:4317"
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]