2. 核心概念：Trace、Span、SpanContext、Baggage、采样率、传播机制

分布式追踪并非单一技术，而是一套由多个核心概念构成的协作模型。理解这些概念是部署与配置追踪系统的基础。本节将逐一拆解 Trace、Span、SpanContext、Baggage、采样率与传播机制，并阐明它们之间的层级关系。

2.1 概念全景图

下图展示了分布式追踪中六个核心概念之间的逻辑关系与数据流向：

2.2 Trace（追踪）

Trace 代表一次完整的请求或事务在分布式系统中的端到端执行路径。它由一组具有相同 TraceID 的 Span 组成，逻辑上构成一个有向无环图（DAG）。

• 唯一标识：每个 Trace 拥有全局唯一的 TraceID（通常为 16 字节或 128 位随机数）。
• 生命周期：从客户端发起请求开始，到最终响应返回结束。
• 可视化：在 Jaeger、Zipkin 等 UI 中，Trace 展示为瀑布图或时间线。

2.3 Span（跨度）

Span 是追踪的最小工作单元，代表一个服务内部或一次远程调用中具有开始时间和结束时间的操作片段。每个 Span 记录以下关键信息：

2.4 SpanContext（跨度上下文）

SpanContext 是跨进程传递追踪状态的核心载体。它包含以下不可变信息：

• TraceID：全局追踪标识。
• SpanID：当前 Span 标识。
• TraceFlags：追踪标志位（如是否被采样）。
• TraceState：W3C TraceContext 定义的供应商无关键值对列表。
• Baggage：用户自定义的透传数据（见 2.5 节）。

SpanContext 通过传播机制（见 2.7 节）在服务之间传递，确保下游服务能够将新创建的 Span 关联到正确的 Trace 树中。

2.5 Baggage（行李）

Baggage 是一组随 SpanContext 跨服务传播的键值对（Key-Value），用于携带业务上下文信息，例如：

• 用户 ID、会话 ID
• 请求来源（如 source=web）
• A/B 测试分组标识

2.6 采样率（Sampling）

在高并发系统中，为每个请求生成完整 Trace 会产生巨大的存储与性能开销。采样率 控制哪些请求被记录和上报。常见采样策略如下：

2.7 传播机制（Propagation）

传播机制 定义了 SpanContext 如何在服务之间传递。主流协议包括：

• W3C TraceContext（推荐）：使用 traceparent 和 tracestate 两个 HTTP Header，是 OpenTelemetry 默认标准。
• Zipkin B3：使用 X-B3-TraceId、X-B3-SpanId、X-B3-ParentSpanId、X-B3-Sampled 四个 Header。
• Jaeger：使用 uber-trace-id 单个 Header 编码所有信息。
• gRPC Metadata：在 gRPC 调用中通过 Metadata 传递。
• 消息队列：通过消息头（如 Kafka Headers、RabbitMQ Headers）传递。

传播机制对比

// 使用 W3C TraceContext 传播器
from opentelemetry import propagate
from opentelemetry.propagators.tracecontext import TraceContextTextMapPropagator

propagate.set_global_textmap(TraceContextTextMapPropagator())

// 同时支持 W3C 和 B3（多传播器）
from opentelemetry.propagators.composite import CompositePropagator
from opentelemetry.propagators.b3 import B3Propagator

propagate.set_global_textmap(
    CompositePropagator([
        TraceContextTextMapPropagator(),
        B3Propagator(),
    ])
)

2.8 核心概念总结表