4. 链路追踪核心概念：Span、Trace、Context Propagation、Baggage

分布式链路追踪是构建可观测性体系的三大支柱之一。要理解链路追踪如何在多服务、多租户环境中传递请求上下文，必须首先掌握其四个核心概念：Span、Trace、Context Propagation 和 Baggage。本节将逐一拆解这些概念，并结合租户隔离场景说明其作用。

4.1 Span：追踪的最小工作单元

Span（跨度）是链路追踪中最基本的逻辑单元，代表一个分布式系统中发生的单个操作或工作步骤。每个 Span 记录了一个操作的开始时间、结束时间、状态以及一组属性（Attributes）和事件（Events）。

一个 Span 的核心数据结构包含以下字段：

4.2 Trace：一次完整请求的端到端视图

Trace（追踪）由一组具有相同 TraceId 的 Span 组成，这些 Span 跨越一个或多个服务，共同描述一次完整请求从入口到出口的完整路径。Trace 本质上是一个有向无环图（DAG），其中每个 Span 通过 ParentSpanId 形成父子关系。

一个典型的 Trace 结构如下：

TraceId: abc123def456
├── Span A (Frontend Service) — 处理 HTTP 请求
│   ├── Span B (Auth Service) — 验证用户身份
│   │   └── Span C (DB Query) — 查询用户权限
│   └── Span D (Order Service) — 处理订单
│       └── Span E (Payment Service) — 执行支付
└── Span F (Frontend Service) — 返回响应

在租户隔离架构中，Trace 的边界尤为重要：

• 租户 A 的请求 产生的 Trace 不应与 租户 B 的请求 的 Trace 混淆。
• 每个 Trace 的根 Span（Root Span）通常由网关或入口服务创建，并在该 Span 中标记 tenant.id。
• 通过 TraceId 可以完整还原一次租户请求的全链路调用拓扑。

4.3 Context Propagation：跨服务传递追踪上下文

Context Propagation（上下文传播）是分布式链路追踪的核心机制。它确保当请求从一个服务传递到另一个服务时，追踪上下文（TraceId、SpanId 等）能够被正确携带和恢复，从而将分散在各服务中的 Span 关联到同一个 Trace 中。

上下文传播通常通过以下方式实现：

• HTTP 传播：通过 HTTP 头传递上下文，如 traceparent、tracestate（W3C Trace Context 标准）。
• 消息队列传播：通过消息头或消息属性传递上下文，如 Kafka 的 Headers、RabbitMQ 的 Message Properties。
• gRPC 传播：通过 gRPC 的 Metadata 传递上下文。
• 进程内传播：通过线程局部变量（ThreadLocal）或协程上下文传递。

以下是一个典型的 HTTP 上下文传播示例：

// 服务 A：创建并注入上下文
Span span = tracer.spanBuilder("handleRequest")
    .setAttribute("tenant.id", "t-001")
    .startSpan();
try (Scope scope = span.makeCurrent()) {
    // 将上下文注入到 HTTP 请求头
    TextMapPropagator propagator = OpenTelemetry.getGlobalPropagators()
        .getTextMapPropagator();
    HttpURLConnection connection = (HttpURLConnection) url.openConnection();
    propagator.inject(Context.current(), connection, (carrier, key, value) ->
        carrier.setRequestProperty(key, value));
    connection.connect();
} finally {
    span.end();
}

// 服务 B：提取并恢复上下文
TextMapPropagator propagator = OpenTelemetry.getGlobalPropagators()
    .getTextMapPropagator();
Context extractedContext = propagator.extract(
    Context.current(), httpServletRequest, (carrier, key) ->
        carrier.getHeader(key));
try (Scope scope = extractedContext.makeCurrent()) {
    // 此时当前 Span 自动成为服务 A 中 Span 的子 Span
    Span span = tracer.spanBuilder("processRequest").startSpan();
    // 从上下文中获取 tenant.id
    String tenantId = Baggage.current().getEntryValue("tenant.id");
    span.setAttribute("tenant.id", tenantId);
    // ... 处理逻辑
    span.end();
}

4.4 Baggage：携带业务上下文的键值对

Baggage（行李）是 OpenTelemetry 提供的一种机制，用于在 Trace 的所有 Span 之间传递键值对形式的业务上下文数据。与 Span Attributes 不同，Baggage 会随着 Context Propagation 自动传播到所有下游服务，而无需在每个 Span 中手动设置。

Baggage 的主要特性：

4.5 四个核心概念的关系总结

Span、Trace、Context Propagation 和 Baggage 共同构成了分布式链路追踪的基石。它们之间的关系可以概括为：

• Span 是构建 Trace 的砖块，每个 Span 记录一个操作。
• Trace 是由 Span 组成的树状结构，代表一次完整请求。
• Context Propagation 是粘合剂，确保 Span 能跨服务关联成 Trace。
• Baggage 是附加数据通道，让业务上下文（如租户 ID）随 Trace 流动。