日志链路追踪实战：用TraceID和MDC根治分布式日志排查难题

凌晨两点被电话叫醒，原因是用户报障“订单一直支付失败”。我打开日志平台，先搜订单号，找到订单服务的日志，发现它调了支付服务，然后去支付服务搜同样的订单号，再根据时间戳手工拼接调用先后顺序，最后靠猜定位到是支付回调超时导致的。整个过程花了四十分钟，其中有二十分钟都耗在了“对时间线”这件事上。那之后我做的第一件事，就是把日志链路追踪在当前项目里彻底落地。

日志链路追踪不是一个新概念，也不是只有大厂才需要的高大上东西。简单说，它就是给每一次外部请求分配一个全局唯一的标识（TraceID），让这个请求经过的所有服务、所有日志都能带上这个ID，排查问题时按TraceID一搜，整条调用链路的日志像被串起来一样按时间顺序排列，谁调了谁、谁慢了多少、哪一步抛了异常，一目了然。这篇文章我不讲虚的，直接讲清楚链路追踪的核心原理、落地模型、技术选型和我在生产环境里踩过的坑，适合正在做微服务拆分、被分布式日志排查折磨的团队参考。

1. 日志链路追踪要解决的核心痛点：从一次线上事故说起

先还原一下没有链路追踪时，日常排查问题到底是什么状态。

1.1 “靠订单号靠时间戳靠猜”的排查方式

在单体应用时代，所有日志写在同一个进程里，按时间排序即可直接看到完整调用过程。但微服务拆开之后，一次用户请求往往要经过网关、用户服务、订单服务、支付服务、消息队列、库存服务至少五六个节点。日志散落在不同的机器、不同的文件、不同的日志索引里。

我见过太多团队是这么排查问题的：先到网关日志里找到请求时间，然后跑到订单服务日志里手动搜同样的订单号，再去支付服务里搜用户ID，再把三段日志按时间放在一起硬拼。运气好时能拼出来，运气不好遇到异步调用、消息重试、定时任务触发，同一个业务会有多条时间线交汇，根本分不清哪条是主链路。

这种情况下最典型的症状是：日志打了，但“串不起来”。下游报错了，你不知道上游传过来的参数是什么；上游超时了，你不知道下游到底卡在哪个方法。每次故障处理都变成一场考古。

1.2 链路追踪到底提供了什么能力

链路追踪解决的是三个层面的问题：

• 串联能力：同一个请求在所有服务中产生的日志，能通过同一个TraceID被关联查询，不需要靠业务单号硬拼。
• 还原能力：可以把一次请求的完整调用路径还原出来，包括调用了哪些服务、每个服务耗时多少、调用的先后顺序、哪一环失败。
• 定位能力：通过耗时分布和错误标记，快速缩小问题范围。是想都不用想直接锁定服务A到服务B之间，还是服务B自身逻辑异常。

1.3 不只是给排查用的，还是给治理用的

链路追踪的价值不只是“出问题时少花时间”，它对日常性能治理同样有用。当TraceID沉淀到日志系统后，你可以统计某个接口在不同链路上的耗时分布，可以分析下游服务的慢调用占比，可以识别出“单次请求扇出”过大的服务。这些都是后续容量评估和架构调整的依据。

我见过不少团队把链路追踪和APM监控混为一谈，但其实它们是互补的。监控解决的是“系统当前有没有问题”，链路追踪解决的是“某个请求到底经历了什么”，两者结合才能形成完整的可观测性体系。这篇文章我的侧重点在日志侧的实现，这是成本最低、见效最快的一种落地方式。

2. 链路追踪的最小落地模型：Trace、Span与TraceID

要落地链路追踪，先要把几个最基础的概念吃透。不然你会在配置和排查时越搞越糊涂。

2.1 Trace、Span、TraceID、SpanID到底怎么理解

用快递寄包裹来类比。

• Trace：一次完整的业务请求，相当于“一单快递从寄出到签收的全程”。
• Span：一次请求中的一个逻辑单元，比如“从上海发往杭州中转站”，这是全程中的一段。
• TraceID：快递单号，整条Trace全局唯一，所有日志里都要带上它。
• SpanID：每个Span自己的ID，用来标识“这是哪一个环节”。
• ParentID：父Span的ID，用来说明“这个环节是由谁发起的”。

所以全链路日志里看到的大概是这样一组字段：

四个字段一组合，就能画出一条完整的调用树。入口服务的spanId是根节点，下游服务的parentId指向上游的spanId，层层嵌套就还原出了调用结构。

2.2 最小技术选型：日志框架的MDC机制

如果你只想用最小的成本达到“日志能按TraceID串联”，那么最直接、最不需要引入额外依赖的方案就是利用日志框架自带的 MDC（Mapped Diagnostic Context，映射诊断上下文）。

Logback里叫MDC，Log4j2里叫ThreadContext，本质上是一样的：它是一个绑定到当前线程的ThreadLocal Map，你可以往里面放键值对，然后在日志pattern里通过占位符把值输出到每行日志中。

这是MDC最典型的使用位置：

java复制import org.slf4j.MDC;

// 在入口处写入
MDC.put("traceId", traceId);
try {
    // 业务处理逻辑
} finally {
    MDC.remove("traceId");
}

在logback.xml的pattern中加入traceId输出：

xml复制<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n</pattern>

加了[%X{traceId}]之后，每行日志会自动带上当前线程MDC里的traceId，不需要在业务代码里手动打日志参数。这一步做完，日志就已经具备“按TraceID搜索”的基础能力了。

2.3 为什么推荐用MDC而不是手动传参打日志

有些团队喜欢在每个方法签名里传requestId，然后在日志消息里拼上去。这样做在单体应用、三层架构里还能凑合，但放到微服务、异步、多线程场景会出现一个很现实的问题：所有涉及日志打印的方法要增加参数，工具类、第三方调用、框架回调代码根本改不动，最后日志格式必然不一致。MDC的好处在于它挂在线程上下文里，业务代码打日志时不需要显式传递，只要日志配置里声明了字段，它就会自动出现在那一行。这也是很多通用日志组件、RPC框架透传traceId时首选MDC的原因。

这里要特别提醒：MDC一定要在finally里清理。因为线程池中的线程会被复用，如果不移除traceId，下一个任务往MDC里放的时候可能读取到上一个任务残留的值，日志串号会非常难排查。

3. 跨服务与跨线程的传递：链路数据不能断

本地MDC解决了“单服务内日志带traceId”的问题，但一次请求要经过多个服务，TraceID必须能在服务之间“接力”传递，否则到了下游服务就丢了，链路还是会断。

3.1 跨HTTP服务传递的标准做法

最通用的跨服务传递方式就是HTTP Header。上游服务生成或接收到traceId之后，把它放入HTTP请求头，下游服务收到请求时从Header里取出并放入自己的MDC。这个逻辑通常写在入口Filter或拦截器里。

具体实现拆成三块：

• 上游在发起HTTP调用时，通过拦截器自动在请求头中注入traceId。比如RestTemplate的ClientHttpRequestInterceptor，或者Spring Cloud OpenFeign的RequestInterceptor。
• 下游在接收入口请求时，通过Filter或HandlerInterceptor优先从Header读取traceId，读到了就放入MDC，没读到就生成一个新的（说明这是一个新的调用链入口）。
• 返回响应时清理MDC。

一个简单的Spring Web入口Filter示例：

java复制@Component
public class TraceIdFilter extends OncePerRequestFilter {

    private static final String TRACE_ID_HEADER = "X-Trace-Id";
    public static final String TRACE_ID_MDC_KEY = "traceId";

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        String traceId = request.getHeader(TRACE_ID_HEADER);
        if (traceId == null || traceId.isEmpty()) {
            traceId = UUID.randomUUID().toString().replace("-", "");
        }
        MDC.put(TRACE_ID_MDC_KEY, traceId);
        response.setHeader(TRACE_ID_HEADER, traceId);
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove(TRACE_ID_MDC_KEY);
        }
    }
}

这里有个细节值得注意：Header名字最好统一约定。如果你用了OpenTelemetry的SDK，它默认会使用traceparent这个Header，格式是00-<trace-id>-<span-id>-<flag>。如果团队技术栈中有OpenTelemetry相关组件，建议优先采用W3C的traceparent标准，这样后续对接开源链路系统时可以无缝衔接。

3.2 跨线程池传递MDC，最容易出问题的环节

业务系统里大量使用线程池执行异步任务，比如异步发送通知、异步写操作日志、批量数据处理。线程池里线程不是创建任务的那个线程，MDC是ThreadLocal实现，天然无法跨线程传递，所以你会看到一种现象：主线程里日志一切正常，进到异步线程之后traceId全没了，整条链路的日志在异步环节“真空”了。

解决思路并不复杂：在提交任务时，把当前线程的MDC上下文拷贝一份，放入任务线程中执行。这里有几个常用做法。

Spring的TaskDecorator是最优雅的接缝点：

java复制public class MdcTaskDecorator implements TaskDecorator {
    @Override
    public Runnable decorate(Runnable runnable) {
        Map<String, String> contextMap = MDC.getCopyOfContextMap();
        return () -> {
            if (contextMap != null) {
                MDC.setContextMap(contextMap);
            }
            try {
                runnable.run();
            } finally {
                MDC.clear();
            }
        };
    }
}

然后在线程池配置里加上这个装饰器：

java复制ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setTaskDecorator(new MdcTaskDecorator());

如果你的项目没有使用Spring的线程池封装，而是直接用ThreadPoolExecutor，那就得自定义Runnable包装类，在execute之前捕获MDC上下文，在run方法开始时放进去。道理和TaskDecorator是一样的，只是写的位置不同。

3.3 消息队列和RPC场景下的传递

走消息队列的异步场景比线程池更隐蔽。生产者把消息发到MQ，消费者在另一个服务、另一个线程里消费，TraceID不会自动跟着消息走。

标准的做法是在消息Header里放入TraceID。以Kafka为例，生产者发送消息时可以在record header中放入traceId：

java复制ProducerRecord<String, String> record = new ProducerRecord<>(topic, data);
record.headers().add("traceId", traceId.getBytes(StandardCharsets.UTF_8));

消费者在处理消息时从header中读取traceId并放入MDC。RocketMQ的message property也是同理。

但这里要区分两种场景。如果消费者处理消息是“延续同一个业务请求”的一部分，应该透传上游的TraceID，保证全链路统一。如果消费者是定时任务、系统事件等新触发的独立流程，那就不该沿用老的TraceID，而是应该新生成一个。判断标准很简单：这个异步动作的业务归属是不是由同一个用户请求直接驱动的。判断错了会造成链路过长或者断链，在日志分析时引发新的困扰。

4. 技术选型：自研轻量方案和开源链路系统怎么选

日志链路追踪的落地路线不止一条。我见过太多团队一上来就上重量级APM，结果运维成本、使用门槛双双失控，最后链路数据没人看，还不如一开始老老实实从日志侧做好TraceID规范化。

4.1 三条主流路线对比

这里把主流路线拉出来对比一下，方便你判断该走哪条。

4.2 我的实际建议：先做日志层的链路，再考虑要不要上APM

如果你的核心痛点是“出问题时日志查起来费劲”，我建议你不要急着部署SkyWalking或者OpenTelemetry，先把日志层的TraceID规范化做了。这个方案工作量可控，一般一个后端开发一周内就能完成核心改造，收益立竿见影：以后排查问题直接按TraceID搜日志，时间线从头拉到尾。

如果你的痛点是“想知道某个接口的完整调用拓扑和耗时分布”，或者团队规模已经到了“日志查到了但不知道哪里慢”的阶段，那再考虑引入Zipkin/Jaeger这类链路分析系统。这些系统之所以能画出链路图，前提也是每一跳都传递了TraceID和SpanID，基础机制和我们上面讲的MDC方案完全一致。所以把日志层的TraceID规范先做好，永远不算白做，它是后续一切链路排查能力的地基。

我个人比较推荐的一个折中方案是：日志层用自研的TraceID规范跑起来，同时预留OpenTelemetry的标准Header字段。这样将来要从自研平滑迁移到OpenTelemetry生态，不需要推翻重来，只需要把Header透传和日志字段对接上即可。

5. 生产环境全链路落地的六个实操步骤

下面这套步骤是我在两个团队里实际推过的完整流程，按顺序走完，链路追踪就能在生产环境真正发挥作用。

5.1 步骤一：统一日志布局与TraceID字段规范

改造之前先和团队约法三章：日志中必须有traceId字段，且输出格式统一。我在项目中使用的logback pattern如下：

xml复制<property name="COMMON_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] [%X{spanId}] %-5level %logger{36} - %msg%n"/>

这里traceId和spanId都输出，方便后续和Zipkin/Jaeger这类系统对齐，前期即使没有链路系统，也不会产生额外成本。规范需要在代码评审中落实，如果PR里新增的日志打印没有走统一logback配置，打回的评审建议里直接注明。

5.2 步骤二：在网关和应用入口生成或透传TraceID

在所有外部请求入口，包括API网关、定时任务入口、MQ消费者入口，统一执行“优先透传、没有再生成”的策略。网关一般有全局过滤器，在Spring Cloud Gateway里实现一个GlobalFilter，把traceId放到ServerWebExchange的header中，再传给下游。内部服务同样实现TraceIdFilter，这样无论入口在哪个位置，整条链路都能续上。

5.3 步骤三：为HTTP客户端和RPC客户端装配透传拦截器

只做入口Filter不做客户端透传是最大的坑。很多团队入口加上了traceId，但服务A调用服务B时没有在HTTP请求头里带上它，导致服务B自己生成了新的traceId，链路在第一个下游调用就断了。

你在项目里需要做以下改造：

• RestTemplate：注册ClientHttpRequestInterceptor，把当前MDC里的traceId写入Header。
• OpenFeign：实现RequestInterceptor，同样写入Header。
• Dubbo / gRPC：利用RPC框架的隐式传参机制，在调用上下文里传递traceId。Dubbo用RpcContext，gRPC用Metadata。
• 自研HTTP工具类：在统一封装的地方加入Header注入逻辑，避免散落的裸HttpURLConnection调用。

这一步骤做完，才能保证服务间调用的链路是连通的。

5.4 步骤四：线程池和异步场景补齐MDC传递

按照上面3.2节的方式，给所有自定义线程池装配MDC传递。如果项目里线程池很多，可以在创建线程池的工具类中统一处理，禁止裸new ThreadPoolExecutor，让所有异步任务都走统一封装。

5.5 步骤五：日志采集侧和处理链路的适配

日志中加了traceId之后，采集和检索侧需要配合调整。以ELK为例，日志采集时解析出traceId字段，在Elasticsearch索引中把traceId映射为keyword类型，否则默认分词会导致精确搜索不生效。另一个细节是日志平台建索引时要用traceId和timestamp做组合排序，保证搜索结果按时间线排列。

如果日志平台支持自定义字段，建议把traceId、spanId、serviceName、env这些类型都埋好，后续做链路分析和告警关联会省很多事。

5.6 步骤六：建立一套可复用的排查模板

链路追踪落地后，把排查路径沉淀成团队的操作手册。比如：

• 线上问题先确认入口网关日志中的traceId。
• 用traceId在日志平台检索，按照时间线查看所有服务相关日志。
• 在结果中看rt最大或者异常最多的Span，定位瓶颈服务。
• 如果数据结果不完整，检查哪个环节丢了traceId（Header没透传、线程池没做MDC传递、异步没有传header）。

把这条路径固化成搜索模板，你会发现新人处理问题的速度也能被拉起来。

6. 我在实战中踩过的坑与排查经验

链路追踪很多细节是测试环境发现不了的，只有生产环境流量大了之后才会暴露。这些坑我基本都踩过，写出来帮你省点时间。

6.1 线程池复用导致的“毛线团”逻辑混乱

我最早做线程池MDC传递时，只做了“放入”没做“清理”。结果线上出现一种非常诡异的日志：一个线程刚开始打印的traceId属于上一个任务，执行到一半才变成当前任务的traceId。排查日志时整条链路完全错乱。根因就是线程复用后MDC里的旧数据没有在任务执行前覆盖、也没在任务结束后清理。修复的关键点在于TaskDecorator里必须在任务开始前setContextMap，任务结束后必须clear，两个动作缺一不可。

6.2 异步日志的MDC坑：AsyncAppender上下文传递

为了性能，我把日志切到logback的AsyncAppender，结果发现JDK的默认线程池策略会在某些情况下重建线程，MDC传递时而生效时而不生效。更重要的是，AsyncAppender默认的discarding策略在队列满了之后会丢日志。排查时看到日志断档，第一反应是链路断了，实际上是异步日志队列满了把低级别日志丢弃了。所以别只看正面的traceId，也要关注异步队列的状态和配置。

6.3 Header名字不统一导致的多团队协作问题

公司里有多个团队，有人用X-Request-Id，有人用X-Trace-Id，有人用X-B3-TraceId。服务A往Header里塞X-Trace-Id，服务B读的是X-Request-Id，链路数据必然断。这个问题在跨团队协作时非常常见。推进链路追踪时，第一个要统一的就是Header命名规范。我建议直接采用W3C标准的traceparent，不仅因为它是开放标准，更重要的是很多开源SDK已经默认支持，未来和外部系统对接时没有障碍。

6.4 TraceID的生成策略：UUID还是雪花ID

TraceID生成方式看似小事，但会直接影响排查效率。UUID不带任何时间信息，看到一串traceId根本不知道它属于哪段时间。我后来在项目里统一用带时间戳的ID生成器，比如基于雪花算法的变体，前几位能看出大致时间，排查时可以先按时间缩小范围，再精确定位TraceID。另外生成器也要注意性能，尽量不要用synchronized加锁的方式，在高并发入口会拖慢接入速度。用现成的开源ID生成器或者基于系统时间加机器ID加序号的方案，都可以满足需求。

6.5 Elasticsearch查询不到traceId：字段被分词了

这是最常见的“配置成功但检索失败”问题。日志收集到ES之后，traceId默认被standard分词器切分成了多个token，输入完整的traceId反而查不到精确匹配。必须在索引模板中把traceId设置为keyword类型。另外日志检索时如果用的是全文搜索而不是字段精确匹配，也可能因为特殊字符导致检索不到，最好都改成traceId: "具体值"这种精确查询方式。

6.6 抽样策略：全量采集和性能之间的平衡

全链路日志数据量是惊人的，尤其是高并发入口，每个请求产生几十行日志，再乘以服务数，存储成本会迅速膨胀。比较合理的做法是分场景抽样：核心交易链路做全量采集，普通查询类接口做百分比采样。在MDC写入时加一个采样判断逻辑，未命中的请求仍然生成traceId但不输出详细链路日志。这样可以很好地平衡数据完整性和存储成本。

7. 最后分享一点个人体会

日志链路追踪这个事，技术含量不算高，难在“规范要落地到每一行代码、每一个线程池、每一次远程调用”。我做过好几个项目的链路改造，最大的感触是：链路追踪不是靠某一个框架或者中间件就能解决的，它是整个团队对日志规范性的共同约束。最简单有效的第一步永远是强制所有服务日志里出现统一的traceId，哪怕暂时没有链路组件没有拓扑图，只要搜索时不靠猜，排查效率的提升就已经肉眼可见了。

如果你正在为分布式排查痛苦，我的建议是从今天开始做三件事：统一日志格式中加入traceId字段、入口生成TraceID、服务和线程池透传。这三步做完，你至少不会再出现在凌晨对着几段日志手工拼时间线的局面。后面要不要上SkyWalking、要不要接OpenTelemetry，那是下一步的事情，先把地基打好，走得稳比走得快重要得多。