SkyWalking【四、链路透传】

在 Spring Boot 应用中，SkyWalking Agent 已经通过字节码增强自动处理了大部分链路追踪的透传工作，包括 HTTP 调用和异步场景。但在某些特定情况下，仍需进行手动配置或注意潜在问题。

🌐 HTTP 调用透传 (RestTemplate / Feign)

SkyWalking Agent 会自动拦截并增强主流的 HTTP 客户端，无需编写任何自定义拦截器。

自动透传：Agent 会自动将当前链路的 TraceId 注入到 RestTemplate 或 Feign 发出的 HTTP 请求头中（如 sw8）。下游服务接收到请求后，Agent 会自动解析并延续链路。
关键前提：确保你的 RestTemplate 或 FeignClient 是由 Spring 容器管理的 Bean。如果手动 new 了一个实例，Agent 将无法拦截，导致链路中断。

🧵 异步与线程池透传

这是链路追踪最容易断裂的场景。SkyWalking Agent 对异步的支持分为两种情况：

自动支持的场景

Agent 会自动增强以下常见异步组件，确保 TraceId 正确传递：
@Async 注解的方法
CompletableFuture
Spring 的 ThreadPoolTaskExecutor
消息队列（如 Kafka, RabbitMQ）的生产与消费

需要手动处理的场景

如果你使用了自定义的线程池（如 java.util.concurrent.ThreadPoolExecutor）或某些第三方异步框架，Agent 可能无法自动覆盖。此时，你需要手动传递上下文。

1、推荐方案：使用 TransmittableThreadLocal (TTL)

TTL 是阿里开源的库，专门用于解决线程池复用导致的 MDC/上下文丢失问题。

引入依赖

com.alibaba
transmittable-thread-local
2.14.4

包装自定义线程池
在创建线程池时，使用 TtlExecutors 进行包装。

import com.alibaba.ttl.threadpool.TtlExecutors;
import java.util.concurrent.*;

// 创建原始线程池
ThreadPoolExecutor originalExecutor = new ThreadPoolExecutor(
5, 10, 60L, TimeUnit.SECONDS, new LinkedBlockingQueue<>(100)
);

// 使用 TTL 包装，自动传递 TraceId 等上下文
ExecutorService ttlExecutor = TtlExecutors.getTtlExecutorService(originalExecutor);

// 提交任务
ttlExecutor.submit(() -> {
// 在此处，SkyWalking Agent 能正确获取到父线程的 TraceId
log.info("异步任务执行中");
});

2、使用包装类

// 包装runable线程任务 org.apache.skywalking.apm.toolkit.trace.CallableWrapper
executor.submit(CallableWrapper.of(fileTask))
// 包装线程池 org.apache.skywalking.apm.toolkit.trace.ExecutorWrapper
ThreadPoolTaskExecutor poolexecutor = new ThreadPoolTaskExecutor();
Executor executor=new ExecutorWrapper(poolexecutor);

⚠️ 核心注意事项

• 区分“链路透传”与“MDC 打印”
  链路透传：SkyWalking Agent 自动完成，确保分布式调用链完整。
  MDC 打印：Agent 会自动将 TraceId 注入主线程的 MDC，但不会自动传递到异步子线程的 MDC。因此，即使链路是完整的，异步线程的日志也可能打印不出 TraceId。使用 TTL 可以同时解决这两个问题。

• 避免手动透传冲突
  不要手动编写 RequestInterceptor 或 ClientHttpRequestInterceptor 来透传 sw8 等 SkyWalking 专用头。这可能导致与 Agent 的自动增强逻辑冲突，引发重复注入或链路异常。

• 验证异步透传
  在配置完成后，务必编写测试用例，在异步任务中打印日志，确认 %tid 或 %X{tid} 能正确输出与主线程一致的 TraceId。

• 版本一致性
  确保 skywalking-agent 的版本与 apm-toolkit-logback-1.x 等工具包版本保持一致，以避免兼容性问题。