3. 链路追踪原理：Trace / Span / SpanContext 的定义与传播

在异步任务编排场景中，一个用户请求往往需要跨多个服务、线程或消息队列才能完成。链路追踪的核心目标，就是为这个分布式请求重建一条完整的调用路径。本章从最基础的三个抽象概念——Trace、Span 和 SpanContext 出发，讲解它们如何定义一次请求的生命周期，以及 TraceId 与 SpanId 如何在异步边界上正确传播。

3.1 核心概念定义

3.2 TraceId 与 SpanId 的生成规则

3.2.1 TraceId

• 全局唯一性：一次请求生命周期内保持不变，所有 Span 共享同一个 TraceId。
• 生成方式：通常由入口服务（如 API 网关或前端）在请求开始时生成。
• 常见算法：
  • 128 位随机数（UUID 或 Snowflake 变体），如 0af7651916cd43dd8448eb211c80319c。
  • 64 位组合：高 32 位为时间戳（秒级），低 32 位为随机数或自增序列，保证分布式环境下的唯一性。

3.2.2 SpanId

• 父-子关系：每个 Span 有唯一的 SpanId，同时记录 ParentSpanId，形成树形结构。
• 生成时机：在创建新 Span 时由当前服务或线程生成。
• 常见算法：64 位随机数，通常使用 ThreadLocalRandom 或 SecureRandom 生成，保证同一 Trace 内不重复。

3.3 传播机制：跨线程与跨进程

链路追踪的难点不在于生成 ID，而在于让 ID 在异步边界上“不丢失”。下面通过一张结构图展示 TraceId 和 SpanId 在典型异步任务编排中的传播路径。

3.4 传播的三种典型场景

3.5 SpanContext 的序列化与反序列化

SpanContext 在跨进程传播时，需要序列化为传输协议支持的格式。以 OpenTelemetry 的 W3C Trace Context 标准为例：

// 序列化后的 traceparent 头格式
// 版本-版本号(1字节) + TraceId(16字节) + SpanId(8字节) + TraceFlags(1字节)
// 示例：
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

// 字段说明：
// 00        : 版本号
// 0af7...   : TraceId（128位，32个十六进制字符）
// b7ad...   : SpanId（64位，16个十六进制字符）
// 01        : TraceFlags（01 表示采样，00 表示不采样）

3.6 异步任务编排中的传播代码示例

下面展示一个使用 Java CompletableFuture 进行异步任务编排时，如何正确传递 SpanContext 的代码片段：

// 1. 定义上下文传播的 Executor 包装器
public class ContextPropagatingExecutor implements Executor {
    private final Executor delegate;

    public ContextPropagatingExecutor(Executor delegate) {
        this.delegate = delegate;
    }

    @Override
    public void execute(Runnable command) {
        // 捕获当前线程的 SpanContext
        SpanContext currentContext = Span.current().getSpanContext();
        delegate.execute(() -> {
            // 在新线程中恢复 SpanContext
            try (Scope scope = Span.makeCurrent(currentContext)) {
                command.run();
            }
        });
    }
}

// 2. 在异步任务编排中使用
Executor executor = new ContextPropagatingExecutor(ForkJoinPool.commonPool());

CompletableFuture<Result> futureA = CompletableFuture
    .supplyAsync(() -> serviceA.call(), executor)
    .thenApplyAsync(result -> transform(result), executor);

CompletableFuture<Result> futureB = CompletableFuture
    .supplyAsync(() -> serviceB.call(), executor);

// 3. 合并结果，所有子任务共享同一个 TraceId
CompletableFuture
    .allOf(futureA, futureB)
    .thenAcceptAsync(ignored -> {
        // 此处 SpanContext 依然有效
        logger.info("所有异步任务完成，TraceId: {}",
            Span.current().getSpanContext().getTraceId());
    }, executor);