一个订单,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
公众号:服务端技术精选
    评论
    0 评论
avatar

取消