如何通过Sleuth在第三方库场景下将traceId/correlationId传播到新线程

核心问题原因 #

你之前用SpanInScope包裹调用无效，是因为第三方库创建的新线程不会自动继承当前线程的Sleuth追踪上下文（TraceContext）和Baggage数据。SpanInScope仅作用于当前线程，无法将上下文传递到第三方库内部创建的线程中。

可行解决办法 #

1. 利用字节码增强自动包装第三方线程池 #

Spring Cloud Sleuth支持通过字节码增强（默认基于Byte Buddy）自动包装JDK的ExecutorService/ThreadPoolExecutor，只需开启相关配置即可实现上下文传播。

在application.yml中添加配置：

spring:
  sleuth:
    executor:
      enabled: true
      # 配置第三方库的包路径，让Sleuth自动拦截该路径下创建的线程池
      include: com.thirdparty.library.package**

原理：Sleuth会拦截指定包下创建的ThreadPoolExecutor实例，自动将其包装为TraceableExecutorService，从而实现追踪上下文的自动传递。

2. 手动包装第三方任务的上下文传播 #

如果字节码增强无法覆盖第三方库的线程池，可通过AOP拦截对第三方库方法的调用，手动包装任务并传递上下文。

示例代码：

@Aspect
@Component
public class ThirdPartyTraceAspect {

    @Autowired
    private Tracer tracer;
    @Autowired
    private BaggageManager baggageManager;

    // 定义切点，匹配第三方库的方法调用
    @Pointcut("execution(* com.thirdparty.library.*.*(..))")
    public void thirdPartyMethodCall() {}

    @Around("thirdPartyMethodCall()")
    public Object wrapTraceContext(ProceedingJoinPoint joinPoint) throws Throwable {
        // 获取当前线程的追踪上下文
        TraceContext currentContext = tracer.currentSpan().context();
        String correlationId = tracer.getBaggage("correlationid").getValue();

        // 包装参数中的Runnable/Callable，执行前恢复上下文
        Object[] wrappedArgs = Arrays.stream(joinPoint.getArgs())
                .map(arg -> {
                    if (arg instanceof Runnable) {
                        return (Runnable) () -> {
                            try (Tracer.SpanInScope scope = tracer.withSpan(currentContext);
                                 BaggageInScope baggage = baggageManager.createBaggage("correlationid", correlationId)) {
                                ((Runnable) arg).run();
                            }
                        };
                    } else if (arg instanceof Callable) {
                        return (Callable<?>) () -> {
                            try (Tracer.SpanInScope scope = tracer.withSpan(currentContext);
                                 BaggageInScope baggage = baggageManager.createBaggage("correlationid", correlationId)) {
                                return ((Callable<?>) arg).call();
                            }
                        };
                    }
                    return arg;
                })
                .toArray();

        return joinPoint.proceed(wrappedArgs);
    }
}

原理：通过AOP拦截第三方库方法调用，将任务包装为带有上下文恢复逻辑的新实例，第三方线程池执行任务时会先恢复追踪上下文和Baggage数据。

3. 自定义ThreadLocal上下文传播 #

如果上述方案都不适用，可通过自定义ThreadLocal存储上下文，再结合字节码增强拦截第三方线程的执行逻辑，手动恢复上下文。

步骤1：自定义上下文存储类

public class CustomTraceContextHolder {
    private static final ThreadLocal<String> TRACE_ID = new ThreadLocal<>();
    private static final ThreadLocal<String> CORRELATION_ID = new ThreadLocal<>();

    public static void setTraceId(String traceId) {
        TRACE_ID.set(traceId);
    }

    public static void setCorrelationId(String correlationId) {
        CORRELATION_ID.set(correlationId);
    }

    public static String getTraceId() {
        return TRACE_ID.get();
    }

    public static String getCorrelationId() {
        return CORRELATION_ID.get();
    }

    public static void clear() {
        TRACE_ID.remove();
        CORRELATION_ID.remove();
    }
}

步骤2：调用第三方库前保存上下文

// 保存当前线程的追踪数据
CustomTraceContextHolder.setTraceId(tracer.currentSpan().context().traceId());
CustomTraceContextHolder.setCorrelationId(tracer.getBaggage("correlationid").getValue());
// 调用第三方库方法
thirdPartyService.executeParallelTask();

步骤3：字节码拦截线程执行逻辑

@Component
public class ThreadContextInterceptor {

    @Autowired
    private Tracer tracer;
    @Autowired
    private BaggageManager baggageManager;

    @PostConstruct
    public void initInterceptor() {
        new ByteBuddy()
                .redefine(Runnable.class)
                .method(ElementMatchers.named("run"))
                .intercept(MethodDelegation.to(this))
                .make()
                .load(getClass().getClassLoader(), ClassLoadingStrategy.Default.INJECTION);
    }

    public void intercept(@SuperCall Callable<Void> superCall) throws Exception {
        String traceId = CustomTraceContextHolder.getTraceId();
        String correlationId = CustomTraceContextHolder.getCorrelationId();

        if (traceId != null && correlationId != null) {
            // 构建并设置TraceContext
            TraceContext context = TraceContext.newBuilder()
                    .traceId(traceId)
                    .spanId(UUID.randomUUID().toString().replace("-", "").substring(0, 16))
                    .build();
            try (Tracer.SpanInScope scope = tracer.withSpan(context);
                 BaggageInScope baggage = baggageManager.createBaggage("correlationid", correlationId)) {
                superCall.call();
            } finally {
                CustomTraceContextHolder.clear();
            }
        } else {
            superCall.call();
        }
    }
}

原理：通过Byte Buddy拦截Runnable的run()方法，执行前从自定义ThreadLocal中取出追踪数据，恢复Sleuth上下文后再执行原任务。

版本适配说明 #

你使用的spring-boot 2.7.7 + spring-cloud-sleuth 3.1.5属于Spring Cloud 2021.0.x（Jubilee）版本，上述方案均适配该版本：

• 字节码增强功能默认开启，只需配置包路径即可生效
• AOP方案无需额外依赖，Spring Boot已集成Spring AOP
• Byte Buddy已包含在Sleuth依赖中，无需额外引入

内容的提问来源于stack exchange，提问作者A_C