Spring Cloud Sleuth问题：parent仅能在本地根为null的断言错误

问题描述 #

在@SpringBootTest环境下测试应用时，遇到偶发的Brave/Spring Cloud Sleuth断言错误：

• 仅引入spring-cloud-starter-sleuth依赖，版本由spring-cloud-dependencies BOM管理，无额外配置
• 执行mvn clean install时偶尔触发错误，错误栈如下：

Exception in thread "ForkJoinPool-1-worker-53" java.lang.AssertionError: Bug (or unexpected call to internal code): parent can only be null in a local root!
        at brave.internal.recorder.PendingSpans.getOrCreate(PendingSpans.java:89)
        at brave.Tracer._toSpan(Tracer.java:410)
        at brave.Tracer.toSpan(Tracer.java:382)
        at brave.Tracer.toSpan(Tracer.java:376)
        at brave.LazySpan.span(LazySpan.java:141)
        at brave.LazySpan.context(LazySpan.java:40)
        at org.springframework.cloud.sleuth.brave.bridge.BraveSpan.context(BraveSpan.java:49)
        at org.springframework.cloud.sleuth.brave.bridge.BraveTracer.nextSpan(BraveTracer.java:64)
        at org.springframework.cloud.sleuth.instrument.async.TraceRunnable.run(TraceRunnable.java:61)
        at java.base/java.util.concurrent.ForkJoinTask$RunnableExecuteAction.exec(ForkJoinTask.java:1426)
        at java.base/java.util.concurrent.ForkJoinTask.doExec(ForkJoinTask.java:290)
        at java.base/java.util.concurrent.ForkJoinPool$WorkQueue.topLevelExec(ForkJoinPool.java:1020)
        at java.base/java.util.concurrent.ForkJoinPool.scan(ForkJoinPool.java:1656)
        at java.base/java.util.concurrent.ForkJoinPool.runWorker(ForkJoinPool.java:1594)
        at java.base/java.util.concurrent.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:183)

原因分析 #

这个错误来自Brave内部的断言校验：当尝试创建新Span时，父Span为null，但当前上下文不符合"本地根Span"的判定条件，触发断言失败。

在测试环境下偶现，核心诱因是异步任务的Trace上下文传递异常：

• ForkJoinPool的线程复用机制导致残留了之前测试的Trace上下文，新任务执行时上下文状态混乱
• Sleuth对ForkJoinTask的Instrumentation在测试场景下存在边界处理缺陷

解决方案 #

1. 禁用ForkJoinPool的Trace增强 #

在测试环境配置文件（如application-test.yml）中添加：

spring.sleuth.instrumentation.async.forkjoin.enabled: false

2. 手动管理Trace上下文 #

在异步任务执行前后手动清理/恢复上下文，避免残留：

import org.springframework.cloud.sleuth.Tracer;
import org.springframework.cloud.sleuth.Span;

// 在异步任务执行前
Span currentSpan = tracer.currentSpan();
try {
    // 清空当前上下文
    tracer.withSpan(null);
    // 执行你的异步业务逻辑
} finally {
    // 恢复原有上下文
    tracer.withSpan(currentSpan);
}

3. 升级依赖版本 #

检查spring-cloud-dependencies的版本，升级到2022.0.x（代号Kilburn）及以上版本，这类异步场景的Bug通常已被修复。

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