4. 异步任务追踪难点：线程池、消息队列、回调函数中的上下文传播

在数据库迁移场景中，异步任务无处不在：批量数据导出由线程池并发执行、变更事件通过消息队列异步消费、迁移进度通过回调函数通知主流程。这些异步边界恰恰是分布式追踪最容易断裂的地方——Span 上下文（Context）一旦无法跨线程、跨进程、跨回调传播，追踪链路就会分裂成孤立的碎片，导致故障排查时无法串联完整调用链。

4.1 异步追踪的核心挑战：上下文丢失

OpenTelemetry 的追踪模型依赖 Context Propagation（上下文传播）将 TraceId 和 SpanId 沿调用链传递。在同步调用中，上下文通过线程局部存储（ThreadLocal）自动传递；但在异步场景下，执行线程发生切换，ThreadLocal 中的上下文会自然丢失。下表总结了三种典型异步模式及其上下文传播风险：

4.2 线程池中的上下文传播

线程池是最常见的异步执行模型。OpenTelemetry 提供了 Context Propagation API 来包装 Runnable 或 Callable，确保任务执行时能恢复提交线程的上下文。

4.2.1 手动包装 vs 自动 instrumentation

Java 示例：使用 Context.wrap() 包装 Runnable：

// 提交线程中获取当前上下文
Context currentContext = Context.current();

executor.submit(() -> {
    // 在任务线程中恢复上下文
    try (Scope scope = currentContext.makeCurrent()) {
        Span span = tracer.spanBuilder("migrate-batch")
                .setAttribute("batch.size", 1000)
                .startSpan();
        try {
            // 执行数据库迁移子任务
            processBatch();
        } finally {
            span.end();
        }
    }
});

如果使用 OpenTelemetry Java Agent 自动 instrumentation，线程池的上下文传播会被自动处理（通过字节码增强包装提交的 Runnable/Callable）。但需要注意：自定义线程池（如使用 new ThreadPoolExecutor() 且未使用标准 Executors 工厂方法）可能不会被自动 instrumentation 覆盖，需要手动包装。

4.2.2 线程池上下文传播架构

下图展示了线程池中上下文传播的完整流程：提交线程将 Context 传递给执行线程，执行线程恢复 Context 后创建子 Span，子 Span 自动继承父 TraceId。

4.3 消息队列中的上下文传播

消息队列场景的上下文传播比线程池更复杂：生产者和消费者通常运行在不同的进程中，ThreadLocal 完全失效，必须通过消息头（Message Headers）将 Context 序列化后传递。

4.3.1 生产者端：注入上下文到消息头

在发送消息前，将当前 Context 注入到消息的 Header 中：

// 生产者：发送消息前注入上下文
Context currentContext = Context.current();
TextMapPropagator propagator = OpenTelemetry.getGlobalPropagator();

Message message = new Message("migration.event", payload);
// 使用 setter 将上下文写入消息头
propagator.inject(currentContext, message, (msg, key, value) -> {
    msg.getHeaders().put(key, value);
});

producer.send(message);

4.3.2 消费者端：从消息头提取上下文

消费者收到消息后，从 Header 中提取 Context，然后基于该 Context 创建消费 Span：

// 消费者：从消息头提取上下文
TextMapPropagator propagator = OpenTelemetry.getGlobalPropagator();

Context extractedContext = propagator.extract(
        Context.current(),
        message,
        (msg, key) -> msg.getHeaders().get(key)
);

try (Scope scope = extractedContext.makeCurrent()) {
    Span span = tracer.spanBuilder("consume-migration-event")
            .setAttribute("event.type", message.getType())
            .startSpan();
    try {
        processEvent(message);
    } finally {
        span.end();
    }
}

4.4 回调函数中的上下文传播

回调函数（如 CompletableFuture 的 thenApply、whenComplete）的上下文传播问题常被忽视。回调在异步线程中执行，提交回调时的上下文已经丢失。

4.4.1 CompletableFuture 回调上下文丢失示例

// ❌ 错误：回调中上下文丢失
CompletableFuture.supplyAsync(() -> fetchData())
        .thenApply(data -> {
            // 这里的 Span 无法关联父 TraceId
            Span span = tracer.spanBuilder("transform-data").startSpan();
            // ...
            span.end();
            return transformedData;
        });

4.4.2 正确做法：使用 Context 包装回调

// ✅ 正确：使用 Context 包装回调
Context currentContext = Context.current();

CompletableFuture.supplyAsync(() -> fetchData())
        .thenApply(data -> {
            try (Scope scope = currentContext.makeCurrent()) {
                Span span = tracer.spanBuilder("transform-data").startSpan();
                try {
                    return transform(data);
                } finally {
                    span.end();
                }
            }
        });

4.4.3 回调上下文传播架构

下图展示了 CompletableFuture 链中上下文传播的正确与错误路径对比：

4.5 异步上下文传播最佳实践清单

• 优先使用自动 instrumentation：OpenTelemetry Java Agent 已覆盖常见线程池（ThreadPoolExecutor、ForkJoinPool）、消息队列客户端（Kafka、RabbitMQ）和 CompletableFuture，可减少手动传播代码。
• 自定义线程池需手动包装：如果使用 new ThreadPoolExecutor() 且未通过 Executors 工厂创建，建议使用 Context.wrap() 包装所有提交的 Runnable/Callable。
• 消息队列务必验证 Header 传播：在测试环境中，通过 OpenTelemetry 的 Span Exporter 检查消费端 Span 的 TraceId 是否与生产端一致。
• 回调链中每个环节都要传播：CompletableFuture 的 thenApply、thenCompose、whenComplete 等每个回调都需要独立捕获和恢复 Context。
• 使用 Context 作用域（Scope）管理生命周期：始终使用 try-with-resources 确保 makeCurrent() 返回的 Scope 被正确关闭，避免上下文泄漏。