2. 分布式追踪基础：Trace与Span概念、TraceId与SpanId的生成规则、Span的生命周期与父子关系

2.1 Trace 与 Span 核心概念

分布式追踪的核心数据模型由 Trace（追踪） 和 Span（跨度） 两个抽象概念构成。理解这两个概念是掌握跨服务链路标记的基石。

2.2 TraceId 与 SpanId 的生成规则

TraceId 和 SpanId 是分布式追踪中用于唯一标识和关联数据的核心标识符。其生成规则直接影响追踪系统的性能和正确性。

2.2.1 TraceId 生成规则

• 全局唯一性： 必须在整个分布式系统集群中全局唯一，通常使用 128 位（16 字节）或 64 位（8 字节）的随机数或组合 ID。
• 常见生成方式：
  • UUID（v4）： 基于随机数生成，简单但长度较长（36字符），索引效率较低。
  • Snowflake 算法变体： 结合时间戳、机器 ID、序列号，生成 64 位长整型，有序且高效。
  • 高 64 位 + 低 64 位： 高 64 位使用时间戳（毫秒级），低 64 位使用随机数或自增序列，兼顾时间有序性和唯一性。
• 传播规则： TraceId 在入口服务（如 API 网关）生成后，通过 W3C Trace-Context 或 Zipkin B3 等协议透传到下游所有服务。

2.2.2 SpanId 生成规则

• 父 Span 内唯一： SpanId 只需在同一个父 Span 下唯一即可，通常使用 64 位随机数或递增序列。
• 生成时机： 在创建新 Span 时由当前服务本地生成，无需全局协调。
• 父子关系绑定： 子 Span 必须记录其父 Span 的 SpanId（即 ParentSpanId），从而形成完整的调用链拓扑。

2.3 Span 的生命周期与父子关系

Span 的生命周期是一个严格的状态机，从创建到结束经历多个阶段。理解其生命周期是正确埋点和分析链路数据的前提。

2.3.1 Span 生命周期状态

2.3.2 Span 父子关系模型

Span 之间的父子关系通过 ParentSpanId 字段建立，形成树形结构。常见的父子关系模式包括：

• 1:1 顺序调用： 服务 A 调用服务 B，A 的 Span 是父，B 的 Span 是子。
• 1:N 扇出调用： 服务 A 同时调用服务 B、C、D，A 的 Span 是父，B、C、D 的 Span 是子（并行执行）。
• N:1 汇聚调用： 多个上游服务调用同一个下游服务，每个上游 Span 作为父，下游 Span 作为子（但下游 Span 只能有一个父，实际表现为多个独立的父子链）。

2.4 分布式追踪核心数据模型（SVG）

下图展示了单个 Trace 中 Span 的树形父子关系、生命周期时间轴以及 TraceId/SpanId 的关联方式。

2.5 Span 生命周期状态机（SVG）

下图展示了 Span 从创建到导出的完整状态流转，帮助理解埋点 SDK 的内部行为。

2.6 代码示例：Span 创建与父子关系绑定

以下代码展示了在 OpenTelemetry SDK 中如何创建 Span 并显式绑定父子关系：

// 示例：在服务A中创建根Span，并在RPC调用时创建子Span
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;

// 1. 获取Tracer实例
Tracer tracer = openTelemetry.getTracer("order-service");

// 2. 创建根Span（Root Span）
Span rootSpan = tracer.spanBuilder("POST /api/order")
    .setSpanKind(SpanKind.SERVER)
    .startSpan();

try (Scope scope = rootSpan.makeCurrent()) {
    // 3. 在根Span上下文中创建子Span（代表RPC调用）
    Span childSpan = tracer.spanBuilder("inventory.check")
        .setParent(Context.current())  // 显式绑定父Span
        .setSpanKind(SpanKind.CLIENT)
        .startSpan();

    try (Scope childScope = childSpan.makeCurrent()) {
        // 执行RPC调用
        childSpan.setAttribute("inventory.itemId", "12345");
        // ... 调用下游服务
    } finally {
        childSpan.end();  // 结束子Span
    }

    // 4. 记录根Span的业务属性
    rootSpan.setAttribute("order.totalAmount", 299.99);
    rootSpan.setStatus(StatusCode.OK);
} catch (Exception e) {
    rootSpan.recordException(e);
    rootSpan.setStatus(StatusCode.ERROR);
} finally {
    rootSpan.end();  // 结束根Span
}