当前位置：首页 > news >正文

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

news 来源：原创 2025/4/23 5:48:55

在这里插入图片描述

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>

注解：

%X{traceId} 会从 MDC 中获取 traceId 的值并输出到日志中。
这种配置方式确保了日志中每条记录都包含唯一的 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}
}

注解：

使用 @Aspect 注解定义一个 AOP 切面。
使用 @Before 和 @After 注解分别在方法调用前后设置和清除 MDC 中的 Trace ID。
这种方式确保了每个方法调用都有唯一的 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 {@Overridepublic 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 上下文}};}
}

注解：

MDC.getCopyOfContextMap() 获取当前线程的 MDC 上下文。
MDC.setContextMap(contextMap) 将上下文传递到新线程。
确保在多线程场景下，每个线程都能正确获取和使用 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;}
}

注解：

使用 ThreadPoolTaskExecutor 定义一个线程池。
通过 setTaskDecorator 方法设置任务装饰器，确保每个线程都能正确处理 MDC 上下文。
这种方式确保了在多线程场景下，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<>("异步方法执行完成");}
}