1. 微服务链路追踪的痛点与traceId的核心价值微服务架构下一次用户请求往往要穿过网关、多个业务服务、缓存、消息队列和数据库调用链像一棵倒过来的树越往下分叉越多。我最早做单体应用时排查一个报错只需要看一份日志文件grep一下异常堆栈就定位到了。但服务拆开之后同一个请求的日志散落在七八个服务的日志文件里时间戳还未必对得齐排查一个问题经常要开着终端窗口来回切靠时间戳和零星的业务字段去猜哪几条日志属于同一次请求。这种体验非常糟糕尤其是线上出问题、业务方在群里催的时候定位效率直接决定故障恢复时长。链路追踪要解决的核心问题就一个把同一次请求在不同服务、不同线程、不同中间件里产生的日志和调用关系串起来。而串起来最轻量、最通用的抓手就是traceId。它本质上是一个全局唯一的字符串在请求进入系统的第一跳生成然后随着调用一路透传下去每个服务在打印日志时都把它带上。这样无论日志分散在哪里只要按traceId过滤就能还原出这次请求的完整轨迹。很多人一上来就想上完整的链路追踪系统比如带Span、带拓扑图、带采样率的那种。我的建议是分阶段来第一阶段先把traceId透传和日志串联做扎实这是投入产出比最高的部分能解决80%的排查痛点第二阶段再考虑接入完整的追踪体系补充耗时分析、依赖拓扑这些能力。这篇先聚焦第一阶段把Spring Cloud Dubbo这个组合下的traceId方案讲透因为这两套框架的上下文传播机制不一样混用的时候坑特别多。适合读这篇的人正在用Spring Cloud做微服务、同时用Dubbo做RPC调用的团队已经上了日志系统但发现日志串不起来的同学以及想搞清楚traceId到底该怎么设计、怎么透传、怎么落地的人。下面我会从上下文传播的底层机制讲起再给出可复现的方案最后聊聊我在实际项目里踩过的坑。2. Spring Cloud与Dubbo的上下文传播机制差异要搞清楚traceId为什么在混合架构里容易丢必须先理解这两套框架各自是怎么传递上下文的。它们的传播载体、拦截时机、线程模型都不一样这是所有问题的根源。2.1 Spring Cloud基于HTTP Header的传播链路Spring Cloud体系里服务间调用主流是HTTPRestTemplate、WebClient、Feign。HTTP是无状态协议上下文只能靠请求头传递。一次请求进来traceId放在Header里比如X-Trace-Id下游服务从Header里读出来再往下一跳继续塞进Header。这条链路的关键节点有几个请求进入时的过滤器Filter或Interceptor负责从Header提取或生成traceId并放进当前线程的上下文通常用ThreadLocal或RequestContextHolder发起调用时客户端拦截器负责把上下文里的traceId写回Header。听起来简单但问题在于异步和线程切换。比如你用Async、用线程池、用CompletableFutureThreadLocal里的值在新线程里是拿不到的traceId就断了。这是Spring Cloud侧最常见的丢traceId场景。另外Spring Cloud生态里其实已经有一套事实标准就是Sleuth现在叫Micrometer Tracing定义的traceId和spanId。它默认用X-B3-TraceId这类Header。如果你自己再造一套X-Trace-Id两套并存容易混乱。我的做法是统一用一套命名要么完全对齐Sleuth的规范要么自定义但全链路只用这一套不要混着来。2.2 Dubbo基于RpcContext与隐式参数的传播链路Dubbo是RPC框架不走HTTP它的上下文传播机制完全不同。Dubbo有自己的RpcContext这是一个ThreadLocal级别的上下文对象可以在消费端设置、在提供端读取。但要注意RpcContext的隐式参数传递是有条件的它默认只在单次调用中有效且需要显式开启。Dubbo传递上下文有两条路一是RpcContext.getContext().setAttachment(key, value)这些attachment会作为隐式参数随RPC请求传到提供端提供端用getAttachment读取二是通过Dubbo的Filter扩展点在消费端Filter里写入、在提供端Filter里读出。attachment的传递在Dubbo 2.7之后有一些行为变化比如异步调用、泛化调用场景下attachment可能不生效这点后面会细说。还有一个容易被忽略的点Dubbo的线程模型。Dubbo提供端默认用固定大小的线程池处理请求消费端的调用线程和提供端的处理线程是两个完全不同的线程。所以traceId必须在跨进程传输时通过attachment带过去到了提供端再重新塞进提供端的ThreadLocal不能指望ThreadLocal自己跨过去。2.3 两套机制混用时的断裂点把两者放一起看断裂点就很清晰了。假设一个请求从Spring Cloud网关进来经过一个Spring Cloud服务HTTP调用再调用一个Dubbo服务Dubbo服务又回调另一个Spring Cloud服务。这条链路上traceId要经历HTTP Header → ThreadLocal → Dubbo attachment → 提供端ThreadLocal → HTTP Header。每一次载体切换如果没有对应的拦截器做转换traceId就丢了。我见过最典型的情况是网关到第一个服务traceId是有的第一个服务调Dubbo时忘了把ThreadLocal里的traceId写进attachment结果Dubbo服务日志里全是空的traceId排查时直接断链。还有一种情况是Dubbo服务处理完再调HTTP服务提供端从attachment读出了traceId放进了ThreadLocal但发起HTTP调用时没有客户端拦截器把它写回Header又断了。所以核心思路是在每一个载体切换的边界上都要有明确的读出来和写进去的动作。下面这张表把边界和对应动作列清楚落地时照着检查就不会漏。调用边界载体切换需要做的动作HTTP入口Header → ThreadLocal过滤器读取Header无则生成存入上下文HTTP出口ThreadLocal → Header客户端拦截器把上下文写入HeaderHTTP → DubboThreadLocal → attachment消费端Filter写入attachmentDubbo入口attachment → ThreadLocal提供端Filter读出并存入上下文Dubbo → HTTPThreadLocal → HeaderHTTP客户端拦截器写入Header异步/线程池父线程 → 子线程手动传递或使用可传递的上下文包装3. traceId方案设计生成、透传与日志落地理解了机制差异方案设计就有了依据。我把整个方案拆成三块traceId怎么生成、怎么透传、怎么落到日志里。每一块都有取舍下面逐个说清楚我的选择和理由。3.1 traceId的生成策略与格式选择生成策略上我强烈建议用雪花算法Snowflake或类似的分布式ID生成器而不是UUID。原因很实际UUID是36位字符串日志里占地方人眼看起来也累雪花算法生成的是64位长整型转成字符串也就19位左右短、有序、可读性好而且天然带时间信息排查时看一眼traceId大概能知道请求发生的时间段。格式上我习惯用traceId加一个spanId的组合。traceId标识整条链路spanId标识当前这一跳。这样在日志里既能按traceId聚合整条链又能按spanId区分具体是哪个服务、哪一跳产生的日志。如果暂时不想引入span的概念至少保证traceId全局唯一且透传完整。生成时机很关键必须在请求进入系统的第一跳生成也就是网关或最外层服务。如果每个服务都自己生成那链路就串不起来了。判断逻辑是从Header或attachment里读读到了就用读不到才生成。这个读不到才生成的逻辑要写在统一的入口过滤器里不要散落在各个业务代码里。注意生成traceId的组件要保证在高并发下不产生重复。雪花算法依赖机器ID和工作ID容器化部署时机器ID的分配要小心否则多实例可能撞ID。如果嫌麻烦用带实例标识的ID生成器也能接受但一定要保证唯一性。3.2 跨HTTP与跨Dubbo的透传实现透传实现的核心是拦截器 统一上下文。我一般会定义一个TraceContext类内部用ThreadLocal更准确说是TransmittableThreadLocal后面讲异步时会说持有traceId和spanId提供get、set、clear方法。所有拦截器都围绕这个类操作。HTTP侧服务端用一个Filter或Spring的HandlerInterceptor在请求进入时读取Header写入TraceContext客户端用ClientHttpRequestInterceptorRestTemplate或RequestInterceptorFeign在发出请求前把TraceContext里的值写进Header。这里有个细节Filter的执行顺序要保证在最前面否则可能业务代码已经执行了traceId还没设置进去。Dubbo侧消费端实现一个Filter在invoke之前把TraceContext的值setAttachment提供端实现一个Filter在invoke之前从getAttachment读出并写入TraceContext调用结束后记得clear避免线程复用导致上下文串味。Dubbo的Filter通过SPI机制注册在resources/META-INF/dubbo目录下配置。// 消费端Filter核心逻辑示意 Activate(group CONSUMER) public class TraceConsumerFilter implements Filter { Override public Result invoke(Invoker? invoker, Invocation invocation) throws RpcException { String traceId TraceContext.getTraceId(); if (traceId ! null) { RpcContext.getContext().setAttachment(traceId, traceId); } return invoker.invoke(invocation); } }提供端Filter逻辑对称从attachment读出来塞进TraceContext并在finally里清理。这里要特别注意Dubbo的attachment在异步调用场景下可能拿不到因为异步调用时RpcContext的上下文可能已经切换了。如果项目里用了Dubbo的异步调用要么改用其他透传方式要么在异步回调里手动补上。3.3 日志框架的MDC集成与格式配置traceId透传到位了最后一步是让它出现在日志里。Java生态里最通用的做法是MDCMapped Diagnostic Context。Logback、Log4j2都支持MDC你只要在入口把traceId放进MDC然后在日志格式里引用它每条日志就自动带上了。具体做法在设置TraceContext的同时调用MDC.put(traceId, traceId)。日志格式pattern里加上%X{traceId}。比如%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] [%X{spanId}] %-5level %logger{36} - %msg%n这样打出来的日志长这样2024-01-15 10:23:45.123 [http-nio-8080-exec-3] [a1b2c3d4e5f6] [span-01] INFO c.e.OrderService - 创建订单成功一眼就能看到traceId排查时直接grep a1b2c3d4e5f6就能捞出整条链路的日志。这里有个坑MDC也是ThreadLocal实现的所以异步场景下同样会丢。解决办法是用TransmittableThreadLocal阿里开源的TTL配合MDC的适配或者在线程池提交任务时手动把MDC的map复制过去。提示MDC的清理很重要。如果用了线程池线程会被复用上一个请求的traceId可能残留在MDC里导致日志串味。一定要在请求结束时MDC.clear()通常放在Filter的finally里。4. 异步与线程池场景下的traceId丢失排查前面反复提到异步场景会丢traceId这一节专门展开讲因为这是实际项目里最高频的坑而且排查起来有点绕。我把常见的丢失场景和排查思路整理出来你可以对照自己的项目检查。4.1 线程池复用导致的上下文串味与丢失先说清楚原理。ThreadLocal的值是绑定在线程上的线程池里的线程是复用的。当你把任务提交给线程池任务实际执行在另一个线程上那个线程的ThreadLocal里没有你当前请求的traceId所以打印出来是空的。更糟的是如果上一个任务执行完没有清理这个线程的ThreadLocal里可能还残留着上一个请求的traceId导致日志串味——A请求的日志里出现了B请求的traceId排查时会被彻底带偏。排查方法先确认日志里traceId是空还是错。空说明没传过去错说明没清理。两种情况处理方式不同。空的情况要加传递逻辑错的情况要加清理逻辑通常两者都要做。解决方案上我推荐用TransmittableThreadLocalTTL。它是对InheritableThreadLocal的增强能在线程池场景下正确传递上下文。用法是把TraceContext内部的ThreadLocal换成TransmittableThreadLocal然后给线程池包一层TtlExecutors.getTtlExecutorService(...)。这样提交任务时TTL会自动把父线程的上下文捕获并传递到子线程执行完再恢复既解决了传递也解决了清理。如果不想引入TTL退而求其次的做法是手动传递在提交任务前把traceId作为参数传进去在任务开头MDC.put任务结束MDC.clear。这种方式可控但啰嗦任务多的时候容易漏。4.2 CompletableFuture与Async的上下文传递CompletableFuture和Async是另外两个高频丢traceId的场景。Async底层也是线程池所以TTL方案同样适用但要注意Async默认用的线程池和业务线程池可能不是同一个需要确认你配置的是哪个然后对它做TTL包装。CompletableFuture更麻烦一点因为它的执行线程取决于你用的是哪个Executor。如果用的是默认的ForkJoinPool.commonPool()那线程完全不受你控制TTL也包不进去。我的建议是永远显式传入自定义的Executor不要用默认的commonPool然后对这个Executor做TTL包装。这样上下文传递就可控了。// 用TTL包装线程池保证traceId跨线程传递 ExecutorService executor TtlExecutors.getTtlExecutorService( new ThreadPoolExecutor(4, 8, 60, TimeUnit.SECONDS, new LinkedBlockingQueue()) ); CompletableFuture.supplyAsync(() - { // 这里能拿到父线程的traceId log.info(异步任务执行); return done; }, executor);还有一个细节CompletableFuture的回调链thenApply、thenAccept等如果不在同一个线程执行上下文也可能断。TTL对这种情况的处理是捕获时传递但回调链的线程切换比较复杂实测下来最稳的做法还是在关键节点手动补一下MDC。4.3 消息队列场景的traceId延续消息队列Kafka、RocketMQ等是另一个断裂点。生产者发送消息时traceId要放进消息头Header或Properties消费者拉取消息时从消息头读出来放进TraceContext和MDC。这样消息的生产和消费才能串到同一条链路上。RocketMQ支持在消息的UserProperty里放自定义属性Kafka支持在RecordHeader里放。生产端在发送前写入消费端在消费时读取。这里要注意消费端的traceId应该延续生产端的而不是新生成一个否则生产消费就断链了。但如果消息是定时消息或延迟消息消费时间可能和发送时间差很远这时候是否延续要看业务语义我一般倾向于延续因为排查时能看出这条消息是哪个请求触发的。排查消息队列丢traceId时先确认消息头里到底有没有写进去。可以在生产端打日志确认写入在消费端打日志确认读取。如果生产端写了消费端读不到多半是消息中间件的版本或配置问题比如某些版本对自定义Header的支持有限制。5. 方案落地中的取舍与踩坑复盘方案讲完了这一节聊聊落地时的取舍和我踩过的坑。这些内容在官方文档里基本看不到但实际项目里非常关键。5.1 自研轻量方案与接入完整追踪体系的取舍很多团队会纠结到底自己写一套traceId透传还是直接上完整的链路追踪系统我的经验是看团队规模和排查诉求。如果团队就十几个人、服务数量在二十个以内、排查诉求主要是把日志串起来那自研一套轻量方案完全够用成本低、可控、没有额外运维负担。自研方案的核心代码量其实不大几个Filter加一个上下文类一两天就能搞定。但如果服务数量上了几十个、调用关系复杂、还需要分析每个环节的耗时和依赖拓扑那自研就不划算了应该考虑接入成熟的追踪体系。不过即便接入完整体系traceId透传这块的坑还是一样的因为底层还是HTTP Header和Dubbo attachment那套机制。所以这篇讲的透传逻辑无论你最终用不用完整体系都是要理解的。我的建议是分两步走先用轻量方案把traceId透传和日志串联做起来解决最痛的排查问题等业务规模上来了再在轻量方案的基础上接入完整体系这时候轻量方案里的上下文类可以平滑迁移不会白做。5.2 几个真实踩坑案例的完整排查链路坑一Dubbo泛化调用丢attachment。项目里有个服务用了Dubbo的泛化调用结果发现traceId传不过去。排查过程先确认消费端Filter有没有执行发现执行了再确认attachment有没有设置发现设置了最后在提供端打断点发现getAttachment返回null。查资料才知道泛化调用场景下attachment的传递有特殊处理需要在invoke时显式带上。解决办法是在泛化调用的代码里手动把traceId塞进attachment或者改用非泛化的方式。坑二网关重写Header导致traceId丢失。网关做路由转发时某些配置会重写或过滤请求头把自定义的traceId Header给过滤掉了。排查时在网关前后各打一条日志发现网关前有traceId、网关后没了定位到是网关的Header过滤规则问题。解决办法是把traceId的Header加入白名单或者调整过滤规则。坑三日志异步Appender导致MDC丢失。用了Logback的AsyncAppender提升日志性能结果发现日志里的traceId时有时无。原因是AsyncAppender把日志事件交给另一个线程处理而MDC是ThreadLocal的那个线程拿不到。解决办法是给AsyncAppender配置includeCallerData或者改用Log4j2的异步日志它对MDC的处理更好再或者用TTL包装。这三个坑的共同点是问题都出在载体切换的边界上。所以排查traceId丢失最有效的方法就是沿着调用链在每一个边界前后各打一条日志看traceId在哪一跳断的。这个方法比盲目看代码高效得多。5.3 性能影响与采样策略的考量最后说说性能。traceId透传本身的开销很小生成一个ID、塞进Header、放进MDC这些都是纳秒到微秒级别对吞吐的影响基本可以忽略。真正有开销的是日志量。每条日志都带上traceId日志体积会增大如果日志系统扛不住可能成为瓶颈。我的做法是日志级别控制好生产环境INFO级别只打关键节点DEBUG级别按需开启日志采样对于超高QPS的接口可以按比例采样记录详细日志但traceId本身还是要全量透传因为排查时你无法预知哪个请求会出问题。如果日志量实在大可以考虑只对错误日志和慢请求记录完整上下文正常请求只记录摘要。还有一个容易忽略的点traceId的长度。前面建议用雪花算法19位左右比UUID的36位省一半空间。日志量大的时候这个差异累积起来很可观。所以格式选择不只是可读性问题也是成本问题。6. 从traceId到完整链路追踪的演进思路traceId透传做扎实之后如果还想往前走一步可以往完整的链路追踪演进。这里简单说说演进思路给有需要的同学一个方向。第一步是在traceId基础上引入spanId和parentSpanId。每次跨服务调用生成一个新的spanId记录parentSpanId这样就能还原出调用树而不只是一条平铺的日志链。span的生成和透传机制和traceId一样只是多了一层父子关系。第二步是记录每个span的耗时。在调用开始和结束各打一个时间戳算出耗时就能分析出哪个环节慢。这一步对性能优化特别有用能快速定位到瓶颈服务。第三步是上报到追踪后端把span数据发到类似Zipkin、Jaeger这样的系统生成可视化的调用拓扑和耗时瀑布图。到这一步链路追踪就完整了。不过要注意上报本身有开销通常要配合采样策略不是所有请求都上报。我的建议是不要一步到位按需演进。先把traceId做好解决排查问题等有性能分析需求了再加span和耗时等团队有专门的观测平台了再考虑上报。每一步都解决一个具体问题不要为了完整而完整。回到最开始的问题链路追踪的本质是让分散的日志重新聚合。traceId是这个聚合的钥匙而透传是保证钥匙能走完全程的关键。Spring Cloud和Dubbo混用的场景下透传的难点在于载体切换把每个边界的读写动作做扎实问题就解决了一大半。剩下的异步、线程池、消息队列这些场景本质上是同一个问题的不同变体理解了ThreadLocal和线程复用的原理排查起来就有章法了。