Spring AOP + Logback + MDC全链路日志追踪

1、背景

• 由于权限管理和安全规范，服务都部署到云上，只能通过日志系统查看日志。

• 然而，面对海量的日志数据，如何快速定位关键信息和调用链路是一个巨大的挑战。

2、方案调研

在 Spring Boot 中实现全链路日志追踪，核心在于在整个请求处理过程中传递一个唯一的 Trace ID。

这个 ID 可以帮助我们在日志中快速定位与特定请求相关的所有日志条目。

以下是几种常见的实现方法：

1. 使用 MDC（Mapped Diagnostic Context）
MDC 是 Logback 等日志框架提供的功能，允许在日志消息中嵌入上下文信息。

我们可以在请求开始时生成一个 Trace ID，并将其放入 MDC，后续的日志记录会自动携带这个 ID。

MDC.put("traceId", traceId); // 将 Trace ID 放入 MDC
logger.info("Processing request..."); // 日志中会自动包含 Trace ID
MDC.remove("traceId"); // 请求结束时清除 Trace ID

2. 使用 Spring Cloud 分布式追踪
如果应用是基于 Spring Cloud 的微服务架构，可以使用 Spring Cloud Sleuth。

它会自动在 HTTP 请求头中注入 Trace ID 和 Span ID，并在日志中输出这些信息。

3. 自定义拦截器和过滤器
通过编写自定义的拦截器或过滤器，可以在请求进入和退出时生成和传递 Trace ID。

拦截器和过滤器可以访问请求和响应对象，从而在 HTTP 头中注入或提取 Trace ID。

4. 使用 OpenTracing 或 Zipkin 等第三方追踪系统
这些系统提供了更强大的分布式追踪功能，包括可视化的追踪数据和服务依赖图。

它们通常与 Spring Cloud Sleuth 集成良好，可以轻松集成到 Spring Boot 应用中。

5. 在日志格式中包含 Trace ID
无论采用哪种方法生成和传递 Trace ID，都应该在日志格式中包含这个 ID，以便在查看或搜索日志时快速定位。

3、方案选择

考虑到项目主要基于 Spring Boot 框架，最终选择通过 Spring AOP + Logback + MDC 实现全链路日志追踪。

这种方式简单易用，且对现有系统侵入性小。

4、方案实施

4.1 添加依赖
以 Maven 为例，添加以下依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-logging</artifactId>
</dependency>

4.2 配置 Logback
在 logback-spring.xml 中配置 Logback 以包含 MDC 中的 Trace ID：

<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>

注解：

1. %X{traceId} 会从 MDC 中获取 traceId 的值并输出到日志中。
2. 这种配置方式确保了日志中每条记录都包含唯一的 Trace ID，便于后续查询和追踪。

4.3 创建 AOP 切面
创建一个 Spring AOP 切面来拦截方法调用，并在方法调用前后设置和清除 MDC 中的 Trace ID：

import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.aspectj.lang.annotation.After;
import org.slf4j.MDC;

@Aspect
public class TraceAspect {

    @Before("execution(* com.example.service.*.*(..))")
    publicvoidbeforeAdvice() {
        StringtraceId= UUID.randomUUID().toString();
        MDC.put("traceId", traceId); // 在方法调用前设置 Trace ID
    }

    @After("execution(* com.example.service.*.*(..))")
    publicvoidafterAdvice() {
        MDC.clear(); // 在方法调用后清除 Trace ID
    }
}

注解：

1. 使用 @Aspect 注解定义一个 AOP 切面。
2. 使用 @Before 和 @After 注解分别在方法调用前后设置和清除 MDC 中的 Trace ID。
3. 这种方式确保了每个方法调用都有唯一的 Trace ID，便于追踪方法的执行链路。

4.4 多线程场景
MDC 是基于线程的，为每个线程维护一个独立的映射。

如果在多线程场景下处理相同的请求，需要确保 Trace ID 能够正确传递到每个线程。

4.4.1 定义任务装饰器

import org.slf4j.MDC;
import org.springframework.core.task.TaskDecorator;

public class MDCTaskDecorator implements TaskDecorator {

    @Override
    public Runnable decorate(Runnable runnable) {
        Map<String, String> contextMap = MDC.getCopyOfContextMap();
        return () -> {
            try {
                if (contextMap != null) {
                    MDC.setContextMap(contextMap); // 将当前线程的 MDC 上下文传递到新线程
                }
                runnable.run();
            } finally {
                MDC.clear(); // 清除 MDC 上下文
            }
        };
    }
}

注解：

1. MDC.getCopyOfContextMap() 获取当前线程的 MDC 上下文。
2. MDC.setContextMap(contextMap) 将上下文传递到新线程。
3. 确保在多线程场景下，每个线程都能正确获取和使用 Trace ID。

4.4.2 定义线程池

import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

public class PoolConfig {

    public Executor taskExecutor() {
        ThreadPoolTaskExecutorexecutor=newThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("mdc-trace-");
        executor.setTaskDecorator(new MDCTaskDecorator()); // 设置任务装饰器
        executor.initialize();
        return executor;
    }
}

注解：

1. 使用 ThreadPoolTaskExecutor 定义一个线程池。
2. 通过 setTaskDecorator 方法设置任务装饰器，确保每个线程都能正确处理 MDC 上下文。
3. 这种方式确保了在多线程场景下，Trace ID 能够正确传递和使用。

4.4.3 使用线程池

import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.AsyncResult;
import org.springframework.stereotype.Service;

@Service
public class AsyncService {

    @Async("taskExecutor")
    public Future<String> asyncMethod()throws InterruptedException {
        log.info("异步方法执行中");
        Thread.sleep(1000);
        return new AsyncResult<>("异步方法执行完成");
    }
}

注解：

1. 使用 @Async 注解指定使用自定义的线程池。
2. 在异步方法中，日志会自动包含 Trace ID，便于追踪异步任务的执行情况。