讲师中心 微信公众号

工具推荐

视频效率加速
SoundView
SoundView

字幕擦除翻译、配音口型同步

立刻MV
立刻MV

低成本歌曲 MV、视频生成

剧云
剧云

中文短剧剧本制作平台

Laper
Laper

剧本策划到成片协作

Java 日志记录怎么用 TraceId 关联调用链路

雨浩君_9444

雨浩君_9444

发布时间:2026-11-19 11:12:28

|

644人浏览过

|

来源于php中文网

原创

在 java 中,使用 traceid 关联调用链路的核心做法是:在请求入口处生成唯一的 traceid,并通过 mdc(mapped diagnostic context)将其存入当前线程的上下文中。随后,配置日志框架(如 logback 或 log4j2)的 patternlayout,将 %x{traceid} 占位符写入日志输出格式。这样,所有经过该线程处理的日志都会自动携带相同的 traceid,从而实现链路的串联与追踪。

Java 日志记录怎么用 TraceId 关联调用链路

如何配置日志模板以输出 TraceId

要让日志文件真正显示 TraceId,必须修改日志输出的 Pattern 配置。Logback 和 Log4j2 都支持通过 %X{key} 语法读取 MDC 中的数据。你需要找到应用的日志配置文件(通常是 logback-spring.xml 或 log4j2-spring.xml),在 <pattern></pattern> 标签中加入 %X{traceId}。配置完成后,每次打印日志时,日志框架会自动从当前线程的 MDC 中查找名为 traceId 的值并替换到对应位置。如果 MDC 中没有该值,则输出为空或默认标记,因此务必确保在请求入口处正确设置。

Java 日志记录怎么用 TraceId 关联调用链路

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %X{traceId} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

上述配置定义了控制台输出格式。其中 %X{traceId} 是关键部分。当应用启动并处理请求时,只要 MDC 中设置了 traceId,控制台打印的每一行日志都会在时间戳和日志级别之后、类名之前显示该 ID。这有助于开发者在海量日志中快速筛选出属于同一请求的所有日志片段。

立即学习“Java免费学习笔记(深入)”;

Java基础版
Java基础版

编写健壮 Java 代码的基础能力,覆盖空指针防护、相等性判断与基础异常处理。

下载

如何在 Spring Boot 中拦截请求并注入 TraceId

在 Spring Boot 应用中,最标准的做法是使用 HandlerInterceptor 或 Filter 来统一处理 TraceId 的生成与清理。推荐使用 HandlerInterceptor,因为它能更精细地控制 Web 请求的生命周期。我们需要实现一个拦截器,在 preHandle 方法中生成 UUID 并存入 MDC,在 afterCompletion 方法中清除 MDC 以防止内存泄漏或线程池复用导致的上下文污染。最后,将该拦截器注册到 Spring MVC 的配置中,使其对所有 URL 生效。

Java 日志记录怎么用 TraceId 关联调用链路

import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.UUID;

@Component
public class TraceIdInterceptor implements HandlerInterceptor {

    private static final String TRACE_ID_KEY = "traceId";

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        // 生成唯一 TraceId
        String traceId = UUID.randomUUID().toString().replace("-", "");
        // 存入 MDC
        MDC.put(TRACE_ID_KEY, traceId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        // 请求结束后清除 MDC,防止线程复用导致数据串扰
        MDC.remove(TRACE_ID_KEY);
    }
}
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final TraceIdInterceptor traceIdInterceptor;

    public WebConfig(TraceIdInterceptor traceIdInterceptor) {
        this.traceIdInterceptor = traceIdInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(traceIdInterceptor)
                .addPathPatterns("/**");
    }
}

这段代码展示了完整的拦截器实现与注册过程。TraceIdInterceptor 在请求到达控制器之前执行,生成一个去除连字符的 UUID 字符串,并通过 MDC.put 绑定到当前线程。关键点在于 afterCompletion 方法,它确保了无论请求成功与否,MDC 中的 traceId 都会被移除。这是防止 Tomcat 等容器线程池复用线程时发生日志 ID 错乱的关键步骤。注册类 WebConfig 通过构造器注入拦截器实例,并将其应用到所有路径 /**。

异步线程中如何传递 TraceId

当业务逻辑涉及异步执行(如使用 @Async 或自定义线程池)时,主线程 MDC 中的 TraceId 不会自动传递给子线程。这是因为 MDC 基于 ThreadLocal 实现,而新创建的线程拥有独立的 ThreadLocal 存储。为了解决这个问题,需要在提交异步任务前,手动捕获主线程的 MDC 上下文,并在子线程执行初期将其恢复。通常的做法是创建一个包装类或使用装饰器模式,在 Runnable 或 Callable 的 run 方法中先复制 MDC 数据,执行完毕后清理。

import org.slf4j.MDC;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
import java.util.Map;

@Service
public class AsyncService {

    @Async
    public void processAsync() {
        // 在异步任务开始时,手动获取父线程的 MDC 并放入当前线程
        Map<String, String> mdcContextMap = MDC.getCopyOfContextMap();
        if (mdcContextMap != null) {
            MDC.setContextMap(mdcContextMap);
        } else {
            // 如果没有父上下文,可以选择生成新的或忽略
            MDC.put("traceId", "ASYNC-" + System.currentTimeMillis());
        }

        try {
            // 实际业务逻辑
            System.out.println("Processing in async thread with traceId: " + MDC.get("traceId"));
        } finally {
            // 清理当前线程的 MDC
            MDC.clear();
        }
    }
}

在 processAsync 方法中,首先调用 MDC.getCopyOfContextMap() 获取主线程的上下文快照。如果存在快照,则通过 MDC.setContextMap() 将其应用到当前异步线程。这保证了异步任务产生的日志依然包含原始的 TraceId。最后,在 finally 块中调用 MDC.clear() 清理当前线程的上下文,避免线程池复用时的残留数据影响后续任务。这种手动传递的方式虽然增加了代码复杂度,但是保证分布式链路追踪完整性的必要手段。

热门AI工具

更多
WorkBuddy

一款AI办公效率工具,主要用于腾讯云推出的AI原生桌面智能体工作台,适合需要提升相关任务效率的用户。

豆包大模型

豆包大模型是一款由字节跳动推出的企业级大语言模型服务平台。

火山引擎

火山引擎是一款面向企业的云计算与AI服务平台。

码上飞
码上飞 Hot

一款基于自然语言的AI应用开发平台,可根据用户描述自动生成应用程序,帮助个人和团队快速完成应用原型与开发。

超级简历WonderCV

一款AI办公效率工具,主要用于免费求职简历模版下载制作,应届生职场人必备简历制作神器,适合需要提升相关任务效率的用户。

UpDream
UpDream Hot

一款AI视频创作工具,主要用于哔哩哔哩推出的自研AI视频创作工具,适合需要提升相关任务效率的用户。

函子Zion

一款支持AI搭建、可视化编辑和多端发布的全栈无代码开发平台。

VibeKnow
VibeKnow Hot

一款AI视频创作工具,主要用于全球首个AI知识视频创作平台,文档、文章、网页,一键生成视频,适合需要提升相关任务效率的用户。

DeepSeek

DeepSeek是一款面向对话、写作、编程和推理场景的AI大模型工具。

相关专题

更多
java
java

Java是一个通用术语,用于表示Java软件及其组件,包括“Java运行时环境 (JRE)”、“Java虚拟机 (JVM)”以及“插件”。php中文网还为大家带了Java相关下载资源、相关课程以及相关文章等内容,供大家免费下载使用。

12937

2023.06.15

java正则表达式语法
java正则表达式语法

java正则表达式语法是一种模式匹配工具,它非常有用,可以在处理文本和字符串时快速地查找、替换、验证和提取特定的模式和数据。本专题提供java正则表达式语法的相关文章、下载和专题,供大家免费下载体验。

10002

2023.07.05

java自学难吗
java自学难吗

Java自学并不难。Java语言相对于其他一些编程语言而言,有着较为简洁和易读的语法,本专题为大家提供java自学难吗相关的文章,大家可以免费体验。

8492

2023.07.31

java配置jdk环境变量
java配置jdk环境变量

Java是一种广泛使用的高级编程语言,用于开发各种类型的应用程序。为了能够在计算机上正确运行和编译Java代码,需要正确配置Java Development Kit(JDK)环境变量。php中文网给大家带来了相关的教程以及文章,欢迎大家前来阅读学习。

1344

2023.08.01

java保留两位小数
java保留两位小数

Java是一种广泛应用于编程领域的高级编程语言。在Java中,保留两位小数是指在进行数值计算或输出时,限制小数部分只有两位有效数字,并将多余的位数进行四舍五入或截取。php中文网给大家带来了相关的教程以及文章,欢迎大家前来阅读学习。

1068

2023.08.02

java基本数据类型
java基本数据类型

java基本数据类型有:1、byte;2、short;3、int;4、long;5、float;6、double;7、char;8、boolean。本专题为大家提供java基本数据类型的相关的文章、下载、课程内容,供大家免费下载体验。

1616

2023.08.02

java有什么用
java有什么用

java可以开发应用程序、移动应用、Web应用、企业级应用、嵌入式系统等方面。本专题为大家提供java有什么用的相关的文章、下载、课程内容,供大家免费下载体验。

3389

2023.08.02

java在线网站
java在线网站

Java在线网站是指提供Java编程学习、实践和交流平台的网络服务。近年来,随着Java语言在软件开发领域的广泛应用,越来越多的人对Java编程感兴趣,并希望能够通过在线网站来学习和提高自己的Java编程技能。php中文网给大家带来了相关的视频、教程以及文章,欢迎大家前来学习阅读和下载。

20611

2023.08.03

GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

20

2026.11.17

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
dev.java 官方:Learn Java
dev.java 官方:Learn Java

共0课时 | 0人学习

Java JDBC数据库连接官方教程
Java JDBC数据库连接官方教程

共0课时 | 0人学习

关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号
PHP中文网订阅号
每天精选资源文章推送

Copyright 2014-2026 https://www.php.cn/ All Rights Reserved | php.cn