有一次排查线上接口变慢打开SkyWalking的Trace页面发现明明一次下单请求里包含了订单校验、库存扣减、积分赠送三个动作链路图上却只看到前两个最后一个积分赠送凭空消失了。点进日志看了半天业务确实执行了但这条链路和主请求彻底断了变成了一段没有任何父级的孤儿Segment。这类问题在微服务项目里太常见了只要代码里用了线程池、Async异步方法或者CompletableFutureSkyWalking的跨线程Trace就会在某个拐角断掉查问题的时候全靠肉眼去对应时间戳效率低到让人抓狂。这篇文章就拿这个场景开刀手把手带你把跨线程的Trace链路重新接上。核心方案是自己写一个RunnableWrapper通过捕获当前线程的ContextSnapshot在子线程执行前恢复上下文再在结束后清理现场让异步任务也能正确挂到父级Segment下面。你会看到完整可复现的Java代码、线程池和SpringAsync的接入姿势、以及我实际踩过的坑。适合正在用SkyWalking做全链路追踪、又恰好被异步链路中断问题困扰的后端开发同学参考。1. 异步链路为什么断TraceContext与线程的生命周期1.1 一条完整Trace在SkyWalking里长什么样在动手写Wrapper之前得先把SkyWalking的数据模型理一遍。一次用户请求进入系统后Agent会为它生成一个全局唯一的TraceId整个请求跨服务、跨线程的所有调用记录都归到这一个TraceId下。Trace往下拆是若干Segment一个Segment通常代表一个服务进程内的一段执行过程Segment再往下拆是Span每个Span表示一次具体的操作比如一次RPC调用、一次数据库查询、一段本地逻辑。这些概念不需要背你就把Trace理解成一次完整业务操作的全程录像Segment是录像里某一台机器上连续拍下的片段Span是片段里的关键镜头。同步调用的场景下Agent通过插桩自动把每个Segment的首尾Span串起来父Span指向子Span链路是通的你才能在SkyWalking UI上看到完整的调用拓扑和耗时瀑布图。问题恰恰出在这里Agent自动串链路的逻辑是建立在同一个线程一路执行到底这个假设上的。你代码里只要一拆线程这个假设就碎了。1.2 异步导致上下文失联的根源SkyWalking在单线程环境里把当前这条链路的关键信息放在一个叫Context的组件里而Context的具体载体是ThreadLocal。也就是说每个线程各有一份自己的上下文父线程的上下文对子线程来说默认是透明的。你在主线程里发起一个请求请求的TraceId、当前Span栈全都在主线程的ThreadLocal里躺着一旦你往线程池丢了一个任务子线程被创建或复用时它是没有这份上下文的。子线程里如果又发起了HTTP调用、数据库查询Agent确实能记录下来但它不知道该往哪条父链路上去挂只能重新开一个新的Segment于是Trace页面里的画面就是主请求是一条链异步任务自己成了一条链两条链都顶着同一个路由前缀但内部没有任何Span的父子关系。这还不是最坑的。线程池里任务执行完线程不会销毁而是回到池子里等下一个任务。如果你在包装异步任务时加了上下文恢复逻辑但没做清理就会出现更诡异的场景一个任务结束后TraceId残留在线程的ThreadLocal里下一个被分配到这个线程的任务一进来先看到了上一个任务的上下文于是新业务的Span被错误挂到上一个任务的Segment下链路串台。比链路断掉更难排查因为你还得去追踪上一个任务是谁。1.3 快照传递而不是上下文搬家了解了断链原因很多人第一反应是能不能直接把Context对象传给子线程用我在早期项目里还真这么试过结果线上出了一堆并发问题。原因很简单Context里保存的是一个动态变化的Span栈子线程在执行业务时会往里压入新Span、弹掉旧Span而同一个Context对象如果被多个子线程同时用栈的压弹操作就变成了并发读写轻则Span错位重则栈溢出整个链路数据直接不可信。正确做法是传递快照。父线程在自己还持有完整上下文的时候调用ContextManager.capture()把当前链路的关键信息TraceId、父SegmentId、父SpanId等拷贝一份这份拷贝就是ContextSnapshot它是只读的。子线程要执行任务前调用ContextManager.continued(snapshot)Agent会根据快照里的信息恢复出一个新的Context并让后续创建的Span自动挂到快照指向的父Span下。任务结束后再把子线程ThreadLocal里的Context清理掉防止串台。整个过程就是三句话父线程抓快照子线程恢复快照任务结束清现场。2. RunnableWrapper核心设计与实现2.1 三步核心设计capture、continued、removeRunnableWrapper这个工具类的核心逻辑不复杂但每一行代码的时机都讲究。先说顺序第一步在提交任务的地方new包装器这个动作会执行ContextManager.capture()拿到调用线程也就是有完整上下文的父线程的ContextSnapshot。第二步线程池或异步执行器真正运行这个Runnable时run方法里先执行ContextManager.continued(snapshot)把快照里记录的父链路信息恢复到当前执行线程。第三步业务代码执行完后在finally块里调用ContextManager.remove()把当前线程ThreadLocal里的Context清掉确保线程下次复用时干干净净。这里最容易被忽略的是时机。很多人会想着把capture写在子线程run方法内部觉得那样更安全实际上完全错误。子线程内部执行capture时ThreadLocal里根本没有父线程的上下文拿到的就是一个空快照恢复了个寂寞。capture必须发生在父线程里、任务还没被提交的那一刹那。这个思路想通了后面所有接入场景都是同一套模式。2.2 可落地的RunnableWrapper代码直接上代码我项目中实际使用版本精简后的样子基于SkyWalking 8.x/9.x的toolkit包import org.apache.skywalking.apm.toolkit.trace.ContextManager; import org.apache.skywalking.apm.toolkit.trace.ContextSnapshot; public class RunnableWrapper implements Runnable { private final Runnable task; private final ContextSnapshot snapshot; private RunnableWrapper(Runnable task) { this.task task; // 关键点这里的capture必须在父线程执行 this.snapshot ContextManager.capture(); } Override public void run() { if (task null) { return; } try { ContextManager.continued(snapshot); task.run(); } finally { ContextManager.remove(); } } public static Runnable wrap(Runnable task) { if (task null) { return null; } // 防止同一任务被重复包装避免二次capture和一层层嵌套 if (task instanceof RunnableWrapper) { return task; } return new RunnableWrapper(task); } }这里我加了两个防御性设计都是实战教训换来的。第一静态工厂方法wrap里判断如果task已经是RunnableWrapper实例就直接返回否则同一个任务经过多层中间件时会被反复包装每包装一次就多一次capture和continued虽然大多数情况下不影响正确性但会有无谓的性能开销排查问题时会干扰视线。第二构造函数是private强制调用方走静态工厂避免有人new完忘了传task导致空指针。2.3 从Runnable扩展到Callable与Supplier线程池里除了提交Runnable还经常提交Callable因为Callable能返回结果。CompletableFuture的supplyAsync系列则接收Supplier。这两种场景使用的包装器逻辑完全一致只是接口方法不同我通常把它们放在同一个工具类里。import java.util.concurrent.Callable; public class CallableWrapperT implements CallableT { private final CallableT task; private final ContextSnapshot snapshot; private CallableWrapper(CallableT task) { this.task task; this.snapshot ContextManager.capture(); } Override public T call() throws Exception { try { ContextManager.continued(snapshot); return task.call(); } finally { ContextManager.remove(); } } public static T CallableT wrap(CallableT task) { if (task null) { return null; } if (task instanceof CallableWrapper) { return task; } return new CallableWrapper(task); } }Supplier版本更简单唯一的区别是get方法没有checked异常import java.util.function.Supplier; public class SupplierWrapperT implements SupplierT { private final SupplierT supplier; private final ContextSnapshot snapshot; private SupplierWrapper(SupplierT supplier) { this.supplier supplier; this.snapshot ContextManager.capture(); } Override public T get() { try { ContextManager.continued(snapshot); return supplier.get(); } finally { ContextManager.remove(); } } public static T SupplierT wrap(SupplierT supplier) { if (supplier null) { return null; } if (supplier instanceof SupplierWrapper) { return supplier; } return new SupplierWrapper(supplier); } }三个包装器的结构几乎可以复制粘贴理解了一个其他两个不用多说。需要注意Callable的call方法声明里throws Exception业务任务里的异常不能吞掉要原样抛出去因为finally里的remove只是清理上下文不应该影响业务异常的上抛。2.4 包装时的三个关键细节第一个细节capture的返回值可能是一个空快照。如果父线程本身就没有上下文比如这个任务是从一个非Web入口的定时任务里发出去的或者上下文在进入线程池之前就被错误清理了capture()能返回对象但快照里没有有效的TraceId。这种情况下continued就是无效操作链路依然是断的。排查时要记住空快照不是包装器的问题而是来源线程没有上下文别在包装器上死磕。第二个细节不要试图在包装器里创建一个新的Trace来顶替。有些同学发现子线程里没有上下文就手动调用ContextManager.createEntrySpan或ContextManager.createLocalSpan想自己开一段。这样做的后果是子任务确实有trace了但它和父线程的TraceId对不上从全链路视角看依然是两条独立的链路。我们要的始终是继承父链路不是另起炉灶。第三个细节包装器应该做到和具体的线程池实现解耦。换句话说RunnableWrapper不关心你用的是单线程的new Thread、无界的Executors.newCachedThreadPool()还是Tomcat线程池它只负责在Runnable的语义层把上下文接上。这样后续想替换线程池、调整参数包装器完全不用动。3. 实战接入线程池、Async、CompletableFuture3.1 手动提交线程池任务先看最直白的手动提交场景。假设有一个线程池负责发通知业务代码里经常见到这种写法ExecutorService notifyPool Executors.newFixedThreadPool(8); notifyPool.submit(() - { // 模拟异步发送短信 sendSms(userId, orderId); });这段代码跑起来sendSms的一切痕迹都不会出现在主请求的Trace里。改造后的写法是notifyPool.submit(RunnableWrapper.wrap(() - { sendSms(userId, orderId); }));就这么一行改动任务提交时先捕获父线程快照子线程执行前恢复之后链路就通了。如果你用的是new Thread(...)同样套一层new Thread(RunnableWrapper.wrap(() - doHeavyWork())).start();这里我想强调一个工程习惯不要在大范围业务代码里到处散落RunnableWrapper.wrap调用更好的做法是把项目的线程池收敛成几个统一的管理入口。比如建一个ExecutorFactory所有线程池的submit、execute方法都先包一层这样即便以后团队里来了新人也不会因为忘记wrap而重新引入断链问题。我见过太多项目前两次接入很顺利等到第5个异步任务时又有人直接裸提交链路又断了一截全靠Code Review兜底累。3.2 Spring Async统一注入TaskDecorator手写线程池可以靠自觉但Spring项目里大量使用的Async注解业务代码里压根接触不到提交点总不能要求每个异步方法内部自己capture。好消息是Spring提供了一个非常友好的扩展点TaskDecorator。它可以在任务真正提交到线程池之前对Runnable做一层装饰包装而且所有走这个线程池的异步任务都会自动生效完全不需要改业务方法。先定义一个装饰器import org.springframework.core.task.TaskDecorator; public class SkyWalkingTaskDecorator implements TaskDecorator { Override public Runnable decorate(Runnable runnable) { return RunnableWrapper.wrap(runnable); } }然后调整异步执行器的配置。如果你项目里用的是默认的ThreadPoolTaskExecutor如下Configuration EnableAsync public class AsyncConfig implements AsyncConfigurer { Override public Executor getAsyncExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(8); executor.setMaxPoolSize(16); executor.setQueueCapacity(200); executor.setThreadNamePrefix(async-task-); executor.setTaskDecorator(new SkyWalkingTaskDecorator()); executor.initialize(); return executor; } }这段配置里有几个细节值得掰开说。setTaskDecorator必须在initialize()之前调用Spring内部会在初始化时把装饰器包装到队列任务提交逻辑里顺序反了是不会生效的。还有AsyncConfigurer接口里的getAsyncExecutor是全局默认异步执行器这样Async方法如果没有显式指定执行器就会自动落到这个配置上相当于统一包了一层RunnableWrapper。如果你的项目已经有了自定义执行器在相应的ThreadPoolTaskExecutorBean上也同样set一下即可。关于这个方案的局限也说清楚如果某个Async方法上显式指定了其他的Executor Bean那那个Bean也必须配了TaskDecorator才会生效。另外如果项目里某些异步逻辑不是通过Spring的异步执行器跑的而是直接注入了某个ExecutorService那还是得靠手动包装。3.3 CompletableFuture里的跨线程场景CompletableFuture是Java 8之后特别常见的异步编排方式它的坑比普通线程池更隐蔽。看这段代码CompletableFuture.supplyAsync(() - queryUser(userId)) .thenApply(user - enrich(user)) .thenAcceptAsync(result - sendNotify(result));supplyAsync默认使用ForkJoinPool.commonPool()它本质是另一个线程池父线程的ContextSnapshot同样传不过去。更麻烦的是thenApply是同步执行还是异步执行取决于依赖的上一个阶段是否已经完成一旦完成它就在当前线程继续跑链路不会断但supplyAsync本身以及thenAcceptAsync这种带Async后缀的方法一定会跨越线程边界。解决方式是按需包装ExecutorService bizPool Executors.newFixedThreadPool(8); CompletableFuture.supplyAsync( SupplierWrapper.wrap(() - queryUser(userId)), bizPool ) .thenApply(user - enrich(user)) .thenAcceptAsync( ConsumerWrapper.wrap(result - sendNotify(result)), bizPool );这里的ConsumerWrapper和前文的SupplierWrapper同理只是接口换成java.util.function.Consumer结构完全一致我通常顺手一起写了放公共类里。简而言之凡是跨线程的入口要么是Runnable要么是Callable要么是Supplier或Consumer包装器都备齐后面遇到任何异步场景都有对应方案。在真实项目中我其实更推荐尽量不在CompletableFuture的链式回调里做太多异步切换。异步每切一次线程链路断裂的概率就增加一次排查时的心智负担也重一层。如果能用同步回调thenApply解决就不要轻易换成thenApplyAsync。3.4 效果验证在SkyWalking UI里确认链路贯通代码写完了怎么确认真的接上了我习惯分三步验证。第一步本地或测试环境启动应用时加上SkyWalking的agent参数确认Agent日志里没有报错UI上能查到当前应用的服务名。第二步主动发一次包含异步逻辑的请求比如调用下单接口然后去SkyWalking的Trace查询页面输入请求的TraceId可以从响应头或日志里拿。第三步点开这条Trace看异步任务对应的Span有没有挂在主请求的Segment下面异步耗时是否出现在父Span的瀑布图里。这里面有个小技巧如果主请求处理得很快异步任务还没跑完你在UI上可能只看到主链路异步任务的Segment要等一会儿才会被Agent上报。所以验证时最好给异步任务里加一个最小耗时比如Thread.sleep(200)确保主链路结束后异步片段仍然能被查询到。另外SkyWalking的UI是按时间窗口查Trace的别忘了把时间段放大否则刚上报的数据可能没进搜索范围。如果你项目里还接入了日志中间件验证可以更细一点看异步任务里打印的日志如果日志中输出的TraceId和主请求一致说明链路打通了。这里的TraceId来自日志插件与MDC的配合后面第4节会详细说。4. 常见问题与排查技巧4.1 高频问题速查表整理一份我实际使用中遇到的高频问题速查表照着排查能省不少时间现象可能原因排查方向与处理办法子线程的Span没有父Span独立成段提交任务时没有在父线程capture检查wrap动作是否发生在主线程不要在Runnable内部capture包装了仍然断链快照本身是空的父线程当时没有上下文在包一层前临时打印snapshot.getTraceId()确认是否有值同一个线程池里有的任务有上下文有的没有只有部分代码走了wrap部分裸提交统一收集线程池提交入口最好用TaskDecorator一次性解决TraceId和日志里的TraceId对不上日志插件未接入MDC或子线程MDC没恢复检查logback/pom依赖参考4.3在包装器里恢复MDC上下文串台任务A的Span挂到任务B下面子线程ThreadLocal没有清理检查finally里是否调用了ContextManager.remove()带Async后缀的CompletableFuture方法还是断链只包了supplyAsync没包异步回调所有跨线程回调入口都套对应包装器这张表里有一半问题根源都是同一个过度自信。写完wrap就认为万事大吉结果包装器的调用路径有漏网之鱼。所以排查时我习惯先在包装器里临时打日志用最笨的办法确认上下文到底传没传过去。4.2 排查traceId丢失的调试思路当链路还是断的时候我会用一条主线快速定位问题在哪个环节。在RunnableWrapper的run方法里临时加上一行日志打印当前快照里的TraceId和恢复后当前线程的TraceId// 临时排查使用确认后删除 System.out.println(snapshot traceId snapshot.getTraceId());快照的TraceId如果为空说明capture时父线程就没有上下文。此时先别查包装器去检查这个任务入口链路是不是从定时任务、MQ消费线程发起的是不是前一个filter/拦截器把Context手动清掉了这些场景父线程本身就没有上下文链路不可能通需要从源头解决。如果快照有TraceId但子线程执行后日志里的TraceId还是不对那就得检查日志输出链路了。SkyWalking要往MDC里放TraceId是需要引入配套日志插件包的比如logback对应的是apm-toolkit-logback-1.x。没有这个依赖子线程哪怕链路通了日志里也不会打印TraceId看起来就像链路断了实际上是日志与Trace没有联动。这个坑迷惑性很强好几次团队同事都栽在这里。还有一类隐蔽问题使用了自定义的线程池装饰器或者中间件比如Hystrix、Seata、Sentinel这些框架它们也喜欢包装Runnable。包装顺序一旦乱掉SkyWalking的包装器可能拿到的就不是原始任务而是一个被中间件改过的对象。排查时把中间件的包装器全部禁用再试试能快速锁定是不是包装顺序冲突。4.3 独门避坑心得最后分享几个我踩了好几次坑才总结出来的经验。第一个是关于上下文清理的。前文代码里finally块执行ContextManager.remove()这一步无论如何不能省。线程池的线程都是复用的不清理的话上一个任务恢复的Context会残留在ThreadLocal里下一个任务过来就直接串到上一条链路上了。更麻烦的是这种串台不是每次必现而是随机出现排查时极其痛苦。我见过有团队因为害怕串台干脆在wrap里每次先执行remove再continued效果也可以但顺序很容易搞混不如统一在finally里remove干净。第二个是关于MDC联动的。如果你的项目用了logback并接了SkyWalking的MDC插件我建议在RunnableWrapper里一并恢复MDC上下文。做法很简单在run方法开头把父线程的MDC map复制一份子线程里恢复最后再清理Override public void run() { MapString, String contextMap MDC.getCopyOfContextMap(); try { MDC.setContextMap(contextMap); ContextManager.continued(snapshot); task.run(); } finally { ContextManager.remove(); MDC.clear(); } }这样异步任务里打出来的日志TraceId和主流程保持一致用日志追踪问题时体验会好很多。不过要注意MDC的setContextMap如果传入null会抛出异常所以最好做一次空值判断再恢复。第三个是关于多层异步嵌套的。如果你的异步任务里又提交了一个异步任务每层提交点都必须做包装。这看起来有点烦但道理和单层一样每一层线程切换都是一次上下文断点不做快照传递就会断。我建议在封装线程池工具类时把wrap动作直接内置到execute/submit方法里比如public class TraceExecutorService implements ExecutorService { private final ExecutorService delegate; public TraceExecutorService(ExecutorService delegate) { this.delegate delegate; } Override public T FutureT submit(CallableT task) { return delegate.submit(CallableWrapper.wrap(task)); } Override public Future? submit(Runnable task) { return delegate.submit(RunnableWrapper.wrap(task)); } }这个包装类会把所有提交入口都统一接上链路传递业务方拿到的是普通的ExecutorService接口用起来没什么感知但又不用到处写wrap。如果你的项目里线程池不好收敛退而求其次至少要做到凡是new Thread或者executor.submit的地方都要包一层团队成员之间做好约定。第四个是版本兼容问题。SkyWalking的各版本API大体一致但细节上比如ContextManager.capture()和ContextManager.continued()在8.x和9.x里都存在签名也稳定所以包装器本身跨版本兼容性不错。但如果你项目用的SkyWalking版本比较老比如6.x建议先查一下toolkit包的API再套用个别版本里方法名有小差异。升级版本后也要重新跑一遍验证用例别想当然以为包装器一定能平滑升级。实际用了RunnableWrapper这套方案之后我最大的感受是它解决的不只是链路画出来好不好看的问题而是真的能让跨线程的异常和耗时回到全链路视野里。以前异步任务报错了你只能从业务日志倒推现在直接在Trace页面点开就能看到具体是哪个环节慢、哪个环节报错排查效率完全不是一个量级。我建议你在自己的项目里做一个公共组件把RunnableWrapper、CallableWrapper、SupplierWrapper和TraceExecutorService统一放进去形成团队默认约定。遇到新场景时先想清楚哪里跨了线程再顺手套一个包装器链路就不会再出现莫名其妙的断头路了。
SkyWalking跨线程Trace断链？RunnableWrapper教你轻松接上
有一次排查线上接口变慢打开SkyWalking的Trace页面发现明明一次下单请求里包含了订单校验、库存扣减、积分赠送三个动作链路图上却只看到前两个最后一个积分赠送凭空消失了。点进日志看了半天业务确实执行了但这条链路和主请求彻底断了变成了一段没有任何父级的孤儿Segment。这类问题在微服务项目里太常见了只要代码里用了线程池、Async异步方法或者CompletableFutureSkyWalking的跨线程Trace就会在某个拐角断掉查问题的时候全靠肉眼去对应时间戳效率低到让人抓狂。这篇文章就拿这个场景开刀手把手带你把跨线程的Trace链路重新接上。核心方案是自己写一个RunnableWrapper通过捕获当前线程的ContextSnapshot在子线程执行前恢复上下文再在结束后清理现场让异步任务也能正确挂到父级Segment下面。你会看到完整可复现的Java代码、线程池和SpringAsync的接入姿势、以及我实际踩过的坑。适合正在用SkyWalking做全链路追踪、又恰好被异步链路中断问题困扰的后端开发同学参考。1. 异步链路为什么断TraceContext与线程的生命周期1.1 一条完整Trace在SkyWalking里长什么样在动手写Wrapper之前得先把SkyWalking的数据模型理一遍。一次用户请求进入系统后Agent会为它生成一个全局唯一的TraceId整个请求跨服务、跨线程的所有调用记录都归到这一个TraceId下。Trace往下拆是若干Segment一个Segment通常代表一个服务进程内的一段执行过程Segment再往下拆是Span每个Span表示一次具体的操作比如一次RPC调用、一次数据库查询、一段本地逻辑。这些概念不需要背你就把Trace理解成一次完整业务操作的全程录像Segment是录像里某一台机器上连续拍下的片段Span是片段里的关键镜头。同步调用的场景下Agent通过插桩自动把每个Segment的首尾Span串起来父Span指向子Span链路是通的你才能在SkyWalking UI上看到完整的调用拓扑和耗时瀑布图。问题恰恰出在这里Agent自动串链路的逻辑是建立在同一个线程一路执行到底这个假设上的。你代码里只要一拆线程这个假设就碎了。1.2 异步导致上下文失联的根源SkyWalking在单线程环境里把当前这条链路的关键信息放在一个叫Context的组件里而Context的具体载体是ThreadLocal。也就是说每个线程各有一份自己的上下文父线程的上下文对子线程来说默认是透明的。你在主线程里发起一个请求请求的TraceId、当前Span栈全都在主线程的ThreadLocal里躺着一旦你往线程池丢了一个任务子线程被创建或复用时它是没有这份上下文的。子线程里如果又发起了HTTP调用、数据库查询Agent确实能记录下来但它不知道该往哪条父链路上去挂只能重新开一个新的Segment于是Trace页面里的画面就是主请求是一条链异步任务自己成了一条链两条链都顶着同一个路由前缀但内部没有任何Span的父子关系。这还不是最坑的。线程池里任务执行完线程不会销毁而是回到池子里等下一个任务。如果你在包装异步任务时加了上下文恢复逻辑但没做清理就会出现更诡异的场景一个任务结束后TraceId残留在线程的ThreadLocal里下一个被分配到这个线程的任务一进来先看到了上一个任务的上下文于是新业务的Span被错误挂到上一个任务的Segment下链路串台。比链路断掉更难排查因为你还得去追踪上一个任务是谁。1.3 快照传递而不是上下文搬家了解了断链原因很多人第一反应是能不能直接把Context对象传给子线程用我在早期项目里还真这么试过结果线上出了一堆并发问题。原因很简单Context里保存的是一个动态变化的Span栈子线程在执行业务时会往里压入新Span、弹掉旧Span而同一个Context对象如果被多个子线程同时用栈的压弹操作就变成了并发读写轻则Span错位重则栈溢出整个链路数据直接不可信。正确做法是传递快照。父线程在自己还持有完整上下文的时候调用ContextManager.capture()把当前链路的关键信息TraceId、父SegmentId、父SpanId等拷贝一份这份拷贝就是ContextSnapshot它是只读的。子线程要执行任务前调用ContextManager.continued(snapshot)Agent会根据快照里的信息恢复出一个新的Context并让后续创建的Span自动挂到快照指向的父Span下。任务结束后再把子线程ThreadLocal里的Context清理掉防止串台。整个过程就是三句话父线程抓快照子线程恢复快照任务结束清现场。2. RunnableWrapper核心设计与实现2.1 三步核心设计capture、continued、removeRunnableWrapper这个工具类的核心逻辑不复杂但每一行代码的时机都讲究。先说顺序第一步在提交任务的地方new包装器这个动作会执行ContextManager.capture()拿到调用线程也就是有完整上下文的父线程的ContextSnapshot。第二步线程池或异步执行器真正运行这个Runnable时run方法里先执行ContextManager.continued(snapshot)把快照里记录的父链路信息恢复到当前执行线程。第三步业务代码执行完后在finally块里调用ContextManager.remove()把当前线程ThreadLocal里的Context清掉确保线程下次复用时干干净净。这里最容易被忽略的是时机。很多人会想着把capture写在子线程run方法内部觉得那样更安全实际上完全错误。子线程内部执行capture时ThreadLocal里根本没有父线程的上下文拿到的就是一个空快照恢复了个寂寞。capture必须发生在父线程里、任务还没被提交的那一刹那。这个思路想通了后面所有接入场景都是同一套模式。2.2 可落地的RunnableWrapper代码直接上代码我项目中实际使用版本精简后的样子基于SkyWalking 8.x/9.x的toolkit包import org.apache.skywalking.apm.toolkit.trace.ContextManager; import org.apache.skywalking.apm.toolkit.trace.ContextSnapshot; public class RunnableWrapper implements Runnable { private final Runnable task; private final ContextSnapshot snapshot; private RunnableWrapper(Runnable task) { this.task task; // 关键点这里的capture必须在父线程执行 this.snapshot ContextManager.capture(); } Override public void run() { if (task null) { return; } try { ContextManager.continued(snapshot); task.run(); } finally { ContextManager.remove(); } } public static Runnable wrap(Runnable task) { if (task null) { return null; } // 防止同一任务被重复包装避免二次capture和一层层嵌套 if (task instanceof RunnableWrapper) { return task; } return new RunnableWrapper(task); } }这里我加了两个防御性设计都是实战教训换来的。第一静态工厂方法wrap里判断如果task已经是RunnableWrapper实例就直接返回否则同一个任务经过多层中间件时会被反复包装每包装一次就多一次capture和continued虽然大多数情况下不影响正确性但会有无谓的性能开销排查问题时会干扰视线。第二构造函数是private强制调用方走静态工厂避免有人new完忘了传task导致空指针。2.3 从Runnable扩展到Callable与Supplier线程池里除了提交Runnable还经常提交Callable因为Callable能返回结果。CompletableFuture的supplyAsync系列则接收Supplier。这两种场景使用的包装器逻辑完全一致只是接口方法不同我通常把它们放在同一个工具类里。import java.util.concurrent.Callable; public class CallableWrapperT implements CallableT { private final CallableT task; private final ContextSnapshot snapshot; private CallableWrapper(CallableT task) { this.task task; this.snapshot ContextManager.capture(); } Override public T call() throws Exception { try { ContextManager.continued(snapshot); return task.call(); } finally { ContextManager.remove(); } } public static T CallableT wrap(CallableT task) { if (task null) { return null; } if (task instanceof CallableWrapper) { return task; } return new CallableWrapper(task); } }Supplier版本更简单唯一的区别是get方法没有checked异常import java.util.function.Supplier; public class SupplierWrapperT implements SupplierT { private final SupplierT supplier; private final ContextSnapshot snapshot; private SupplierWrapper(SupplierT supplier) { this.supplier supplier; this.snapshot ContextManager.capture(); } Override public T get() { try { ContextManager.continued(snapshot); return supplier.get(); } finally { ContextManager.remove(); } } public static T SupplierT wrap(SupplierT supplier) { if (supplier null) { return null; } if (supplier instanceof SupplierWrapper) { return supplier; } return new SupplierWrapper(supplier); } }三个包装器的结构几乎可以复制粘贴理解了一个其他两个不用多说。需要注意Callable的call方法声明里throws Exception业务任务里的异常不能吞掉要原样抛出去因为finally里的remove只是清理上下文不应该影响业务异常的上抛。2.4 包装时的三个关键细节第一个细节capture的返回值可能是一个空快照。如果父线程本身就没有上下文比如这个任务是从一个非Web入口的定时任务里发出去的或者上下文在进入线程池之前就被错误清理了capture()能返回对象但快照里没有有效的TraceId。这种情况下continued就是无效操作链路依然是断的。排查时要记住空快照不是包装器的问题而是来源线程没有上下文别在包装器上死磕。第二个细节不要试图在包装器里创建一个新的Trace来顶替。有些同学发现子线程里没有上下文就手动调用ContextManager.createEntrySpan或ContextManager.createLocalSpan想自己开一段。这样做的后果是子任务确实有trace了但它和父线程的TraceId对不上从全链路视角看依然是两条独立的链路。我们要的始终是继承父链路不是另起炉灶。第三个细节包装器应该做到和具体的线程池实现解耦。换句话说RunnableWrapper不关心你用的是单线程的new Thread、无界的Executors.newCachedThreadPool()还是Tomcat线程池它只负责在Runnable的语义层把上下文接上。这样后续想替换线程池、调整参数包装器完全不用动。3. 实战接入线程池、Async、CompletableFuture3.1 手动提交线程池任务先看最直白的手动提交场景。假设有一个线程池负责发通知业务代码里经常见到这种写法ExecutorService notifyPool Executors.newFixedThreadPool(8); notifyPool.submit(() - { // 模拟异步发送短信 sendSms(userId, orderId); });这段代码跑起来sendSms的一切痕迹都不会出现在主请求的Trace里。改造后的写法是notifyPool.submit(RunnableWrapper.wrap(() - { sendSms(userId, orderId); }));就这么一行改动任务提交时先捕获父线程快照子线程执行前恢复之后链路就通了。如果你用的是new Thread(...)同样套一层new Thread(RunnableWrapper.wrap(() - doHeavyWork())).start();这里我想强调一个工程习惯不要在大范围业务代码里到处散落RunnableWrapper.wrap调用更好的做法是把项目的线程池收敛成几个统一的管理入口。比如建一个ExecutorFactory所有线程池的submit、execute方法都先包一层这样即便以后团队里来了新人也不会因为忘记wrap而重新引入断链问题。我见过太多项目前两次接入很顺利等到第5个异步任务时又有人直接裸提交链路又断了一截全靠Code Review兜底累。3.2 Spring Async统一注入TaskDecorator手写线程池可以靠自觉但Spring项目里大量使用的Async注解业务代码里压根接触不到提交点总不能要求每个异步方法内部自己capture。好消息是Spring提供了一个非常友好的扩展点TaskDecorator。它可以在任务真正提交到线程池之前对Runnable做一层装饰包装而且所有走这个线程池的异步任务都会自动生效完全不需要改业务方法。先定义一个装饰器import org.springframework.core.task.TaskDecorator; public class SkyWalkingTaskDecorator implements TaskDecorator { Override public Runnable decorate(Runnable runnable) { return RunnableWrapper.wrap(runnable); } }然后调整异步执行器的配置。如果你项目里用的是默认的ThreadPoolTaskExecutor如下Configuration EnableAsync public class AsyncConfig implements AsyncConfigurer { Override public Executor getAsyncExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(8); executor.setMaxPoolSize(16); executor.setQueueCapacity(200); executor.setThreadNamePrefix(async-task-); executor.setTaskDecorator(new SkyWalkingTaskDecorator()); executor.initialize(); return executor; } }这段配置里有几个细节值得掰开说。setTaskDecorator必须在initialize()之前调用Spring内部会在初始化时把装饰器包装到队列任务提交逻辑里顺序反了是不会生效的。还有AsyncConfigurer接口里的getAsyncExecutor是全局默认异步执行器这样Async方法如果没有显式指定执行器就会自动落到这个配置上相当于统一包了一层RunnableWrapper。如果你的项目已经有了自定义执行器在相应的ThreadPoolTaskExecutorBean上也同样set一下即可。关于这个方案的局限也说清楚如果某个Async方法上显式指定了其他的Executor Bean那那个Bean也必须配了TaskDecorator才会生效。另外如果项目里某些异步逻辑不是通过Spring的异步执行器跑的而是直接注入了某个ExecutorService那还是得靠手动包装。3.3 CompletableFuture里的跨线程场景CompletableFuture是Java 8之后特别常见的异步编排方式它的坑比普通线程池更隐蔽。看这段代码CompletableFuture.supplyAsync(() - queryUser(userId)) .thenApply(user - enrich(user)) .thenAcceptAsync(result - sendNotify(result));supplyAsync默认使用ForkJoinPool.commonPool()它本质是另一个线程池父线程的ContextSnapshot同样传不过去。更麻烦的是thenApply是同步执行还是异步执行取决于依赖的上一个阶段是否已经完成一旦完成它就在当前线程继续跑链路不会断但supplyAsync本身以及thenAcceptAsync这种带Async后缀的方法一定会跨越线程边界。解决方式是按需包装ExecutorService bizPool Executors.newFixedThreadPool(8); CompletableFuture.supplyAsync( SupplierWrapper.wrap(() - queryUser(userId)), bizPool ) .thenApply(user - enrich(user)) .thenAcceptAsync( ConsumerWrapper.wrap(result - sendNotify(result)), bizPool );这里的ConsumerWrapper和前文的SupplierWrapper同理只是接口换成java.util.function.Consumer结构完全一致我通常顺手一起写了放公共类里。简而言之凡是跨线程的入口要么是Runnable要么是Callable要么是Supplier或Consumer包装器都备齐后面遇到任何异步场景都有对应方案。在真实项目中我其实更推荐尽量不在CompletableFuture的链式回调里做太多异步切换。异步每切一次线程链路断裂的概率就增加一次排查时的心智负担也重一层。如果能用同步回调thenApply解决就不要轻易换成thenApplyAsync。3.4 效果验证在SkyWalking UI里确认链路贯通代码写完了怎么确认真的接上了我习惯分三步验证。第一步本地或测试环境启动应用时加上SkyWalking的agent参数确认Agent日志里没有报错UI上能查到当前应用的服务名。第二步主动发一次包含异步逻辑的请求比如调用下单接口然后去SkyWalking的Trace查询页面输入请求的TraceId可以从响应头或日志里拿。第三步点开这条Trace看异步任务对应的Span有没有挂在主请求的Segment下面异步耗时是否出现在父Span的瀑布图里。这里面有个小技巧如果主请求处理得很快异步任务还没跑完你在UI上可能只看到主链路异步任务的Segment要等一会儿才会被Agent上报。所以验证时最好给异步任务里加一个最小耗时比如Thread.sleep(200)确保主链路结束后异步片段仍然能被查询到。另外SkyWalking的UI是按时间窗口查Trace的别忘了把时间段放大否则刚上报的数据可能没进搜索范围。如果你项目里还接入了日志中间件验证可以更细一点看异步任务里打印的日志如果日志中输出的TraceId和主请求一致说明链路打通了。这里的TraceId来自日志插件与MDC的配合后面第4节会详细说。4. 常见问题与排查技巧4.1 高频问题速查表整理一份我实际使用中遇到的高频问题速查表照着排查能省不少时间现象可能原因排查方向与处理办法子线程的Span没有父Span独立成段提交任务时没有在父线程capture检查wrap动作是否发生在主线程不要在Runnable内部capture包装了仍然断链快照本身是空的父线程当时没有上下文在包一层前临时打印snapshot.getTraceId()确认是否有值同一个线程池里有的任务有上下文有的没有只有部分代码走了wrap部分裸提交统一收集线程池提交入口最好用TaskDecorator一次性解决TraceId和日志里的TraceId对不上日志插件未接入MDC或子线程MDC没恢复检查logback/pom依赖参考4.3在包装器里恢复MDC上下文串台任务A的Span挂到任务B下面子线程ThreadLocal没有清理检查finally里是否调用了ContextManager.remove()带Async后缀的CompletableFuture方法还是断链只包了supplyAsync没包异步回调所有跨线程回调入口都套对应包装器这张表里有一半问题根源都是同一个过度自信。写完wrap就认为万事大吉结果包装器的调用路径有漏网之鱼。所以排查时我习惯先在包装器里临时打日志用最笨的办法确认上下文到底传没传过去。4.2 排查traceId丢失的调试思路当链路还是断的时候我会用一条主线快速定位问题在哪个环节。在RunnableWrapper的run方法里临时加上一行日志打印当前快照里的TraceId和恢复后当前线程的TraceId// 临时排查使用确认后删除 System.out.println(snapshot traceId snapshot.getTraceId());快照的TraceId如果为空说明capture时父线程就没有上下文。此时先别查包装器去检查这个任务入口链路是不是从定时任务、MQ消费线程发起的是不是前一个filter/拦截器把Context手动清掉了这些场景父线程本身就没有上下文链路不可能通需要从源头解决。如果快照有TraceId但子线程执行后日志里的TraceId还是不对那就得检查日志输出链路了。SkyWalking要往MDC里放TraceId是需要引入配套日志插件包的比如logback对应的是apm-toolkit-logback-1.x。没有这个依赖子线程哪怕链路通了日志里也不会打印TraceId看起来就像链路断了实际上是日志与Trace没有联动。这个坑迷惑性很强好几次团队同事都栽在这里。还有一类隐蔽问题使用了自定义的线程池装饰器或者中间件比如Hystrix、Seata、Sentinel这些框架它们也喜欢包装Runnable。包装顺序一旦乱掉SkyWalking的包装器可能拿到的就不是原始任务而是一个被中间件改过的对象。排查时把中间件的包装器全部禁用再试试能快速锁定是不是包装顺序冲突。4.3 独门避坑心得最后分享几个我踩了好几次坑才总结出来的经验。第一个是关于上下文清理的。前文代码里finally块执行ContextManager.remove()这一步无论如何不能省。线程池的线程都是复用的不清理的话上一个任务恢复的Context会残留在ThreadLocal里下一个任务过来就直接串到上一条链路上了。更麻烦的是这种串台不是每次必现而是随机出现排查时极其痛苦。我见过有团队因为害怕串台干脆在wrap里每次先执行remove再continued效果也可以但顺序很容易搞混不如统一在finally里remove干净。第二个是关于MDC联动的。如果你的项目用了logback并接了SkyWalking的MDC插件我建议在RunnableWrapper里一并恢复MDC上下文。做法很简单在run方法开头把父线程的MDC map复制一份子线程里恢复最后再清理Override public void run() { MapString, String contextMap MDC.getCopyOfContextMap(); try { MDC.setContextMap(contextMap); ContextManager.continued(snapshot); task.run(); } finally { ContextManager.remove(); MDC.clear(); } }这样异步任务里打出来的日志TraceId和主流程保持一致用日志追踪问题时体验会好很多。不过要注意MDC的setContextMap如果传入null会抛出异常所以最好做一次空值判断再恢复。第三个是关于多层异步嵌套的。如果你的异步任务里又提交了一个异步任务每层提交点都必须做包装。这看起来有点烦但道理和单层一样每一层线程切换都是一次上下文断点不做快照传递就会断。我建议在封装线程池工具类时把wrap动作直接内置到execute/submit方法里比如public class TraceExecutorService implements ExecutorService { private final ExecutorService delegate; public TraceExecutorService(ExecutorService delegate) { this.delegate delegate; } Override public T FutureT submit(CallableT task) { return delegate.submit(CallableWrapper.wrap(task)); } Override public Future? submit(Runnable task) { return delegate.submit(RunnableWrapper.wrap(task)); } }这个包装类会把所有提交入口都统一接上链路传递业务方拿到的是普通的ExecutorService接口用起来没什么感知但又不用到处写wrap。如果你的项目里线程池不好收敛退而求其次至少要做到凡是new Thread或者executor.submit的地方都要包一层团队成员之间做好约定。第四个是版本兼容问题。SkyWalking的各版本API大体一致但细节上比如ContextManager.capture()和ContextManager.continued()在8.x和9.x里都存在签名也稳定所以包装器本身跨版本兼容性不错。但如果你项目用的SkyWalking版本比较老比如6.x建议先查一下toolkit包的API再套用个别版本里方法名有小差异。升级版本后也要重新跑一遍验证用例别想当然以为包装器一定能平滑升级。实际用了RunnableWrapper这套方案之后我最大的感受是它解决的不只是链路画出来好不好看的问题而是真的能让跨线程的异常和耗时回到全链路视野里。以前异步任务报错了你只能从业务日志倒推现在直接在Trace页面点开就能看到具体是哪个环节慢、哪个环节报错排查效率完全不是一个量级。我建议你在自己的项目里做一个公共组件把RunnableWrapper、CallableWrapper、SupplierWrapper和TraceExecutorService统一放进去形成团队默认约定。遇到新场景时先想清楚哪里跨了线程再顺手套一个包装器链路就不会再出现莫名其妙的断头路了。
![别再问“AI写作工具谁第一”了：变态反应学毕业论文，真正好用的是组合拳 [特殊字符]](http://pic.xiahunao.cn/yaotu/别再问“AI写作工具谁第一”了：变态反应学毕业论文，真正好用的是组合拳 [特殊字符])
