使用Spring Boot和MDC实现跨线程链路日志追踪

在分布式系统中，链路日志追踪是一项至关重要的功能，可以帮助我们快速定位问题，了解每个请求在系统中的完整调用链路。本文将介绍如何在Spring Boot应用中使用MDC（Mapped Diagnostic Context）实现链路日志追踪，以及如何在使用@Async注解的异步任务中传递traceId。

一、链路日志追踪的基本实现

首先，我们需要在Spring Boot项目中引入相关的依赖，并配置日志。接下来，我们将创建一个自定义的拦截器，用于生成traceId并将其添加到MDC中。

1. 添加依赖

在你的Spring Boot项目的pom.xml文件中，添加以下依赖：

<!-- Spring Boot Actuator -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- Spring Boot Web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- SLF4J MDC -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>1.7.30</version>
</dependency>

2. 创建请求拦截器

新建一个RequestInterceptor类，实现org.springframework.web.servlet.HandlerInterceptor接口。在preHandle方法中，生成一个唯一的ID，将其添加到MDC中。在afterCompletion方法中，清除MDC的内容。

import org.slf4j.MDC;
import org.springframework.web.servlet.HandlerInterceptor;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.UUID;

public class RequestInterceptor implements HandlerInterceptor {
    private static final String TRACE_ID = "traceId";

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String traceId = UUID.randomUUID().toString();
        MDC.put(TRACE_ID, traceId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        MDC.remove(TRACE_ID);
    }
}

3. 注册请求拦截器

在Spring Boot的主配置类中，添加一个WebMvcConfigurer的实现，将RequestInterceptor注册为一个拦截器。

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 {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new RequestInterceptor());
    }
}

4. 配置日志

在src/main/resources目录下，创建或编辑logback-spring.xml文件，将MDC的traceId添加到日志格式中。

<configuration>
    <springProperty scope="context" name="springAppName" source="spring.application.name"/>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>%d{HH:mm:ss.SSS} [%X{traceId}] [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
</appender>

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

至此，我们已经实现了基本的链路日志追踪功能。每个请求都会被分配一个唯一的traceId，并在日志中显示。

5.响应参数添加traceId

原先接口响应参数是不包括traceId的，为了方便定位问题，需要在响应的参数中增加。

添加后：

 

@ApiModel(description = "统一返回结果")
public class Result<T> implements Serializable {

    private static final long serialVersionUID = 2872694413533224206L;
    @ApiModelProperty(value = "返回编码", example = "200")
    private Integer code;
    @ApiModelProperty(value = "统一失败信息描述", example = "参数校验失败")
    private String message;
    @ApiModelProperty(value = "返回的数据")
    private T data;
    @ApiModelProperty(value = "日志id")
    private String logId;

    /**
     * 自定义：构造结果
     *
     * @param resultEnum 结果枚举类
     * @param data       结果数据
     * @return 结果
     */
    public static Result build(ResultEnum resultEnum, String message, Object data) {
        return new Result(resultEnum.getCode(), message, data,MDC.get(Constants.TRACE_ID));
    }

}

二、在@Async异步任务中传递traceId

当我们在Spring Boot应用中使用@Async注解来处理异步任务时，由于MDC是基于ThreadLocal实现的，traceId在异步子线程中可能会丢失。为了解决这个问题，我们需要自定义一个AsyncConfigurer，并使用包含traceId的线程工厂创建线程池。

1. 启用异步支持

在你的Spring Boot应用配置类中添加@EnableAsync注解，启用异步支持：

import org.springframework.scheduling.annotation.EnableAsync;

@Configuration
@EnableAsync
public class AppConfig {
}

2. 实现 Runnable 接口，用于在多线程环境下设置和清除日志跟踪标识（Trace ID）

新建一个TraceIdRunnable类，用于多线程下创建traceId。

构造方法 TraceIdRunnable(Runnable delegate, String traceId)：接受两个参数，一个是要执行的任务对象 delegate，另一个是要设置的跟踪标识 traceId。这些参数被存储在成员变量中。

import org.slf4j.MDC;


public class TraceIdRunnable implements Runnable {
    private final Runnable delegate;
    private final String traceId;

    public TraceIdRunnable(Runnable delegate, String traceId) {
        this.delegate = delegate;
        this.traceId = traceId;
    }

    @Override
    public void run() {
        MDC.put(Constants.TRACE_ID, traceId);
        try {
            delegate.run();
        } finally {
            MDC.remove(Constants.TRACE_ID);
        }
    }
}

3. 创建一个自定义的ThreadFactory

新建一个TraceIdThreadFactory类，用于创建包含traceId的线程。

import org.slf4j.MDC;

import java.util.concurrent.Executors;
import java.util.concurrent.ThreadFactory;

public class TraceIdThreadFactory implements ThreadFactory {
    private final ThreadFactory delegate = Executors.defaultThreadFactory();

    @Override
    public Thread newThread(Runnable r) {
        String traceId = MDC.get("traceId");
        return delegate.newThread(new TraceIdRunnable(r, traceId));
    }
}

4. 创建一个自定义的AsyncConfigurer

新建一个CustomAsyncConfigurer类，实现AsyncConfigurer接口。在getAsyncExecutor方法中，使用TraceIdThreadFactory创建线程池。

import org.springframework.aop.interceptor.AsyncUncaughtExceptionHandler;
import org.springframework.aop.interceptor.SimpleAsyncUncaughtExceptionHandler;
import org.springframework.scheduling.annotation.AsyncConfigurer;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

import java.util.concurrent.Executor;

@Configuration
@EnableAsync
public class CustomAsyncConfigurer implements AsyncConfigurer {
    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(25);
        executor.setThreadFactory(new TraceIdThreadFactory());
        executor.initialize();
        return executor;
    }

    @Override
    public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
        return new SimpleAsyncUncaughtExceptionHandler();
    }
}

现在，异步任务使用@Async注解创建的子线程将能够访问traceId。这是因为我们通过自定义TraceIdThreadFactory将traceId从父线程传递给子线程。在子线程的run方法中，我们将traceId设置到MDC中，并在任务执行完成后清除它。这样，子线程中的日志记录也将包含traceId。

三、总结

通过本文，我们学习了如何在Spring Boot应用中使用MDC实现链路日志追踪，以及如何在异步任务中传递traceId。这样，我们可以轻松地查看每个请求在系统中的完整调用链路，从而定位问题和优化性能。

以下是我们在本文中完成的主要步骤：

1. 使用HandlerInterceptor创建一个请求拦截器，生成traceId并将其添加到MDC中。
2. 在WebMvcConfigurer实现中注册请求拦截器。
3. 配置日志，将MDC的traceId添加到日志格式中。
4. 使用@EnableAsync注解启用异步支持。
5. 创建一个自定义的ThreadFactory，用于在异步子线程中传递traceId。
6. 创建一个自定义的AsyncConfigurer，并使用包含traceId的线程工厂创建线程池。

希望这篇文章能帮助你更好地理解Spring Boot中链路日志追踪的实现，以及如何在异步任务中传递traceId。