一个订单,6 个服务,5 种日志格式:查了 40 分钟
凌晨 1 点,一个订单查了 40 分钟
用户报“支付成功,订单列表是空的”。给了订单号,我打开 Kibana 搜:网关有这条,订单服务有,库存服务一条都没有;支付服务有,但用的是另一串 UUID。6 个服务,5 种日志格式——有的打 requestId,有的打 orderNo,有的什么都不打。
最后是拿时间戳加手机号后四位硬凑出来的:库存服务在扣减时抛了异常,被 catch 之后只打了一句“库存扣减失败”,没带订单号,也没带 traceId。40 分钟里,35 分钟花在“这条日志到底属于哪个请求”上。
结论前置:这篇给一套最小可跑的方案,4 段代码——Filter 生成和清理、AOP 补业务维度、TaskDecorator 把上下文带过线程池、Feign 拦截器把 traceId 传出去,再约定 Kafka 头。做完之后,搜一个 traceId,6 个服务的日志按时间排成一条线。
做完长这样
一条日志长这样:
01:12:33.508 INFO [9f3c1a2b-417263] [InventoryService#deduct] [biz-3] InventoryClient - deduct sku=1001 qty=2
前半段是时间、级别、traceId,中括号里是“哪个方法、哪个线程”。前端报障时把响应头里的 traceId 贴过来,直接搜,不用再问“大概几点、哪个用户”。
搜索也简单:Kibana 里 traceId:"9f3c1a2b-417263",或者命令行 grep 9f3c1a2b-417263 app.log。
环境准备
- Spring Boot 3.2.x / JDK 21
- Spring Cloud 2023.0.x(OpenFeign 4.1.x)
- spring-kafka 3.1.x(链路里有 MQ 才需要)
- 依赖:starter-web、starter-aop、starter-openfeign、spring-kafka
已经在用 OpenTelemetry 或 SkyWalking 的团队,上下文由它们负责,不必自己拼这一套;这套方案适合不想引入 agent、只想把日志串起来的场景。
分步实现
1 入口:Filter 里生成,finally 里清理
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class TraceIdFilter extends OncePerRequestFilter {
public static final String TRACE_ID = "traceId";
public static final String HEADER = "X-Trace-Id";
@Override
protected void doFilterInternal(HttpServletRequest req, HttpServletResponse resp,
FilterChain chain) throws ServletException, IOException {
String traceId = req.getHeader(HEADER);
if (traceId == null || traceId.isBlank()) {
traceId = Long.toHexString(System.currentTimeMillis()) + "-"
+ ThreadLocalRandom.current().nextInt(100000, 999999);
}
MDC.put(TRACE_ID, traceId);
resp.setHeader(HEADER, traceId); // 回写给调用方,前端报障直接带走
try {
chain.doFilter(req, resp);
} finally {
MDC.clear(); // 线程会被复用,必须清
}
}
}
三个点决定它能不能“串到底”。
上游传来了 header 就复用,不重新生成——否则网关一个、服务一个,链路从第二个服务就断了。生成时带时间戳前缀,出问题时可以按前缀粗略排序,比纯 UUID 好排查。finally 里的 MDC.clear() 是硬要求,Tomcat 线程是复用的,不清就会把上一个请求的 traceId 带给下一个。
为什么用 Filter 而不是 HandlerInterceptor:Filter 在 DispatcherServlet 之前执行,能覆盖静态资源、错误页、没进 Controller 的请求;Interceptor 在之后,异常处理链路里经常已经拿不到上下文。
2 AOP 补业务维度:从“哪个接口”到“在干什么”
Filter 只知道 URI,POST /api/order 看不出这一步是在校验库存还是在下单。AOP 补上类名和方法名:
@Aspect
@Component
public class TraceAspect {
private static final Logger log = LoggerFactory.getLogger(TraceAspect.class);
@Around("@within(org.springframework.web.bind.annotation.RestController)")
public Object around(ProceedingJoinPoint pjp) throws Throwable {
String biz = pjp.getSignature().getDeclaringType().getSimpleName()
+ "#" + pjp.getSignature().getName();
MDC.put("biz", biz);
long start = System.nanoTime();
try {
return pjp.proceed();
} finally {
long cost = (System.nanoTime() - start) / 1_000_000;
if (cost > 200) {
log.warn("slow method cost={}ms", cost); // traceId 自动带上
}
MDC.remove("biz");
}
}
}
切面不生成 traceId,只补字段,所以它必须在 Filter 之后跑。打印慢方法日志时不用手动拼 traceId——日志框架会从 MDC 取。
注意这里用 MDC.remove("biz") 而不是 clear():clear 会把 Filter 放进去的 traceId 一起删掉,同一次请求后续的日志就没 ID 了。
3 异步:MDC 不会自己过线程池
MDC 底层是 ThreadLocal,@Async 换到子线程,上下文就是空的。给 ThreadPoolTaskExecutor 挂一个 TaskDecorator,任务提交时快照、执行时恢复:
@Configuration
public class ExecutorConfig {
@Bean("bizExecutor")
public ThreadPoolTaskExecutor bizExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(8);
executor.setMaxPoolSize(32);
executor.setQueueCapacity(256);
executor.setThreadNamePrefix("biz-");
executor.setTaskDecorator(runnable -> {
Map<String, String> ctx = MDC.getCopyOfContextMap();
return () -> {
if (ctx != null) MDC.setContextMap(ctx);
try {
runnable.run();
} finally {
MDC.clear(); // 线程池复用,不清理就会串号
}
};
});
executor.initialize();
return executor;
}
}
用的时候必须指定执行器:@Async("bizExecutor")。Spring Boot 默认的 applicationTaskExecutor 不会自动带装饰器,别以为写了 @Async 就自动传上下文。
手工 new Thread()、CompletableFuture.supplyAsync() 不带 executor 的情况也一样,MDC 是空的。要不就统一收口到自己这个线程池,要不就在提交前显式把 traceId 作为参数传进去。
4 出站:Feign 和 MQ 把 traceId 传下去
服务内闭环了,跨服务还得靠协议头。Feign 一个拦截器:
@Configuration
public class FeignTraceConfig {
@Bean
public RequestInterceptor traceIdInterceptor() {
return template -> {
String traceId = MDC.get("traceId");
if (traceId != null && !traceId.isBlank()) {
template.header("X-Trace-Id", traceId);
}
};
}
}
RestTemplate 用 ClientHttpRequestInterceptor,逻辑一样。Kafka 则把 traceId 写进消息头,不要塞进消息体——塞 body 意味着消费端要先解析业务 JSON 才能拿到 ID,等于把可观测性绑死在业务格式上。消费端用 Spring Kafka 的 RecordInterceptor 从 record.headers() 取出放进 MDC,处理完在 afterRecord 或监听器的 finally 里清掉。
定时任务没有 HTTP 入口,Filter 不会触发,得在任务开头自己生成一个再 put,否则那一批日志没有 ID,跟在线请求也对不上。
验证:三个场景
同步请求:curl -H "X-Trace-Id: test-001" localhost:8080/api/order/1,日志里应该原样出现 test-001;不带 header 时应该出现一个“时间戳-6 位随机数”的 ID,并且响应头里也有。
异步请求:@Async 方法里的日志和父线程是同一个 traceId。连续压 100 次,检查有没有出现“上一次请求的 ID”——出现了就是 MDC.clear() 漏了。
跨服务:调下游后,在下游服务的日志里 grep 同一个 traceId;Kafka 消费端同理。
最后,5 条坑
- 只 put 不 clear——线程池复用会串号,日志里出现别人的 traceId,比没有 ID 更难查。
- 只加 Filter 不加 TaskDecorator——
@Async、CompletableFuture里的日志全是空 ID。 - 跨服务只打日志不传 header——下游重新生成,一条链路断成两截。
- Kafka 把 traceId 塞消息体——消费端必须先解析业务字段,格式一改就断。
- 拿 traceId 当 spanId 用——一次请求调了 5 个下游,共用一个 ID 分不出哪段慢,得再补一个 spanId。
日志格式只改一处:把 %X{traceId:-} 和 %X{biz:-} 加进 Logback 的 pattern。:- 后面留空是缺省值,防止启动阶段没有 MDC 的日志打出 null。
traceId 的价值不在“有”,在“每个服务都愿意带上、而且不串号”。
你们的 traceId 是在网关统一生成,还是每个服务各生成一个?有没有遇到过线程池复用导致日志串号?
关注我,每周拆一个真实生产故障。
标题:一个订单,6 个服务,5 种日志格式:查了 40 分钟
作者:jiangyi
地址:http://www.jiangyi.space/articles/2026/11/11/1794148788633.html
公众号:服务端技术精选
评论