📚 课程目录第3章分布式追踪基础

3、分布式追踪基础：Trace、Span、SpanContext、Baggage，以及 OpenTelemetry 标准

分布式追踪是构建可观测性体系的三大支柱之一，也是实现质量门禁规则自动验证与 MTTR 复盘口径对齐的核心数据源。本节将系统梳理分布式追踪的四个核心概念——Trace、Span、SpanContext、Baggage，并介绍当前业界标准 OpenTelemetry 的数据模型与传播机制。

3.1 核心概念与数据模型

分布式追踪的本质是记录一次请求在多个微服务、中间件、数据库之间的完整调用链路。其数据模型由以下四个层次构成：

概念	定义	关键属性	作用域
Trace	一次完整请求的端到端调用链路，由多个 Span 组成的有向无环图（DAG）	TraceID（全局唯一）、开始时间、结束时间	全局
Span	Trace 中的一个工作单元，代表一次具体的操作（如 RPC 调用、数据库查询）	SpanID、ParentSpanID、OperationName、StartTime、EndTime、Status、Attributes、Events	单个服务/组件
SpanContext	跨进程传递的追踪上下文，包含 TraceID、SpanID、TraceFlags、Tracestate	TraceID、SpanID、TraceFlags（采样标记）、Tracestate（供应商扩展）	进程间传播
Baggage	随请求传播的键值对上下文，用于传递业务属性（如用户 ID、请求来源）	键值对集合（字符串），可跨服务传递	全局传播

质量门禁视角： Trace 是 MTTR 复盘口径自动验证的“全景地图”，Span 是“关键证据点”，SpanContext 是“跨服务证据链”，Baggage 是“业务标签”。门禁规则需要同时校验这四个层次的完整性与一致性。

3.2 Trace 与 Span 的层级关系

一个 Trace 由一棵 Span 树构成，根 Span（Root Span）代表入口请求，子 Span 代表下游调用。每个 Span 通过 ParentSpanID 指向其父 Span，形成严格的层级结构。

3.3 SpanContext 与跨进程传播

SpanContext 是分布式追踪跨服务传播的核心载体。当服务 A 调用服务 B 时，必须将 SpanContext 通过 HTTP 头、gRPC 元数据或消息队列属性传递给下游，下游服务从中提取 TraceID 和 ParentSpanID，创建新的子 Span。

传播协议示例（W3C TraceContext）：

# HTTP 请求头格式
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
tracestate: congo=t61rcWkgMzE,rojo=00f067aa0ba902b7

# 字段解析：
# 00: 版本号
# 0af7651916cd43dd8448eb211c80319c: TraceID（16字节，32位十六进制）
# b7ad6b7169203331: SpanID（8字节，16位十六进制）
# 01: TraceFlags（01 表示采样，00 表示未采样）

3.4 Baggage：业务上下文传递

Baggage 用于在请求链路中传递业务级键值对，例如用户 ID、请求来源、实验分组等。与 SpanContext 不同，Baggage 不参与追踪拓扑构建，而是为 Span 提供业务维度的标签。

特性	SpanContext	Baggage
用途	追踪链路拓扑构建	业务上下文传递
传播范围	所有下游服务	所有下游服务
数据量	固定长度（约 50 字节）	可变，建议不超过 128 个键值对
安全敏感	否（仅追踪 ID）	是（可能包含 PII 信息）
质量门禁用途	校验链路完整性	传递门禁规则标签（如门禁版本、规则 ID）

Baggage 使用规范： 禁止在 Baggage 中传递敏感信息（密码、、身份证号）。质量门禁系统建议使用 Baggage 传递 gate.rule.version、gate.checkpoint.id 等元数据，便于复盘时关联门禁规则执行上下文。

3.5 OpenTelemetry 标准与数据模型

OpenTelemetry（OTel）是 CNCF 孵化的可观测性标准，统一了分布式追踪、指标、日志的采集与导出。其追踪数据模型对 Trace、Span、SpanContext、Baggage 进行了标准化定义。

3.5.1 OTel Span 数据模型

// OTel Span 核心字段（Protobuf 定义简化）
message Span {
  bytes trace_id = 1;           // 16 字节 TraceID
  bytes span_id = 2;            // 8 字节 SpanID
  bytes parent_span_id = 3;     // 8 字节 ParentSpanID（根 Span 为空）
  string name = 4;              // 操作名称
  int32 kind = 5;               // Span 类型：0=INTERNAL, 1=SERVER, 2=CLIENT, 3=PRODUCER, 4=CONSUMER
  int64 start_time_unix_nano = 6;
  int64 end_time_unix_nano = 7;
  repeated KeyValue attributes = 8;  // 自定义属性
  repeated Event events = 9;         // 事件（如异常、日志）
  Status status = 10;                // 状态：Unset/Ok/Error
  // ... 其他字段
}

3.5.2 OTel 传播器与上下文注入

OTel 定义了三种标准传播器，用于在不同协议中传递 SpanContext 和 Baggage：

W3C TraceContext 传播器： 使用 traceparent 和 tracestate 头传递 SpanContext，是业界推荐标准。
Baggage 传播器： 使用 baggage 头传递键值对，格式为 key1=value1,key2=value2。
Jaeger 传播器（兼容模式）： 使用 uber-trace-id 头，用于与旧版 Jaeger 系统互操作。

3.6 质量门禁规则中的追踪验证要点

在质量门禁规则驱动 MTTR 复盘口径自动验证的场景中，分布式追踪数据需要满足以下校验条件：

Trace 完整性： 每个 Trace 必须有且仅有一个根 Span，所有子 Span 的 ParentSpanID 必须指向有效的父 Span，不能出现孤儿 Span。
Span 时间连续性： 子 Span 的开始时间必须 ≥ 父 Span 的开始时间，子 Span 的结束时间必须 ≤ 父 Span 的结束时间，不允许出现时间倒挂。
SpanContext 传播一致性： 跨服务调用时，下游服务接收到的 TraceID 必须与上游一致，SpanID 必须为新生成且唯一。
Baggage 传递完整性： 门禁规则标签（如规则版本号、检查点 ID）必须从入口服务完整传递到所有下游服务，不能中途丢失。
错误传播标记： 当某个 Span 状态为 Error 时，其父 Span 及根 Span 应通过 Attributes 或 Events 记录错误传播路径，便于 MTTR 复盘时定位根因。

门禁规则示例（伪代码）：

rule "Trace 完整性校验"
  when
    span.parent_span_id != "" 
    && not exists(span.parent_span_id in all_spans.span_id)
  then
    fail("孤儿 Span 检测: " + span.span_id + " 的父 Span 不存在")

rule "Baggage 传递校验"
  when
    service == "gateway" 
    && baggage["gate.rule.version"] == null
  then
    fail("入口服务缺少门禁规则版本标签")

3.7 本章小结

分布式追踪的四个核心概念——Trace、Span、SpanContext、Baggage——构成了可观测性数据的基础骨架。OpenTelemetry 标准统一了数据模型与传播协议，使得跨服务、跨平台的追踪数据能够被一致地采集、传播和验证。在质量门禁规则驱动 MTTR 复盘口径自动验证的课程中，理解这些基础概念是后续设计校验规则、构建验证管道的前提。