如何使用 SLF4J 的 MDC, 實現全鏈路追蹤？
作者：猿java
本文，我們分析了如何使用MDC?實現全鏈路追蹤，通過合理使用 SLF4J的MDC?，可以在分布式系統中實現全鏈路的 traceId 追蹤，提升日志的可讀性和追蹤能力。
在分布式系統或微服務架構中，全鏈路追蹤（Full-Chain Tracing） 對診斷和監控系統的性能至關重要。這篇文章，我們將詳細介紹如何使用 SLF4J 的 MDC 實現全鏈路的 traceId。
一、什么是 SLF4J 的MDC？
MDC（Mapped Diagnostic Context，映射診斷上下文）是 SLF4J 提供的一種上下文機制，它允許在日志記錄時附加一些關鍵的上下文信息（如 traceId、userId 等），這些信息可以在日志格式中被引用，從而豐富日志內容，便于后續的日志分析和追蹤。
二、如何實現全鏈路 traceId？
1. 生成或提取 traceId
在請求的入口點，通常來說是客戶端（比如瀏覽器、移動應用等，也可以是 Web 控制器、服務網關等）生成一個唯一的 traceId，
import org.slf4j.MDC;
import java.util.UUID;
public void handleRequest(HttpServletRequest request) {
String traceId = request.getHeader("X-Trace-Id");
if (traceId == null || traceId.isEmpty()) {
traceId = UUID.randomUUID().toString();
}
MDC.put("traceId", traceId);
try {
// 處理請求的業務邏輯
} finally {
MDC.remove("traceId"); // 確保線程安全，避免內存泄漏
}
}2. 配置日志格式以包含 traceId
在日志配置文件（如 logback.xml 或 log4j2.xml）中，將 traceId 添加到日志輸出格式中。例如，使用 Logback 時：
<configuration>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>[%d{yyyy-MM-dd HH:mm:ss}] [traceId:%X{traceId}] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<root level="info">
<appender-ref ref="STDOUT" />
</root>
</configuration>這樣，每條日志都會包含 traceId，便于后續追蹤。
3. 傳播 traceId 到下游服務
當一個服務調用下游服務時，需要確保 traceId 被傳遞。通常通過 HTTP 頭部傳遞，例如使用X-Trace-Id或者tracestate 頭：
import org.springframework.web.client.RestTemplate;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpEntity;
public void callDownstreamService() {
String traceId = MDC.get("traceId");
HttpHeaders headers = new HttpHeaders();
headers.set("X-Trace-Id", traceId);
HttpEntity<String> entity = new HttpEntity<>(headers);
RestTemplate restTemplate = new RestTemplate();
restTemplate.exchange("http://downstream-service/api", HttpMethod.GET, entity, String.class);
}4. 在下游服務中設置 traceId 到 MDC
下游服務在接收到請求時，需要從請求頭中提取 traceId 并設置到 MDC：
public void handleDownstreamRequest(HttpServletRequest request) {
String traceId = request.getHeader("X-Trace-Id");
if (traceId != null && !traceId.isEmpty()) {
MDC.put("traceId", traceId);
} else {
traceId = UUID.randomUUID().toString();
MDC.put("traceId", traceId);
}
try {
// 業務邏輯處理
} finally {
MDC.remove("traceId");
}
}5. 處理多線程環境下的 traceId 傳播
在多線程環境中，如使用線程池或異步任務，MDC 的上下文默認不會自動傳播到子線程。需要手動傳遞 traceId：
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
public void executeAsyncTask() {
String traceId = MDC.get("traceId");
ExecutorService executor = Executors.newFixedThreadPool(10);
executor.submit(() -> {
MDC.put("traceId", traceId);
try {
// 異步任務邏輯
} finally {
MDC.remove("traceId");
}
});
}為了簡化多線程環境下的 MDC 傳播，可以使用像 MDC Decorator 或自定義 Executor 來自動管理 MDC。
三、使用攔截器或過濾器統一管理 traceId
為了避免在每個請求處理方法中手動設置和清理 traceId，可以使用 Spring 的攔截器（Interceptor）或 Servlet 過濾器（Filter）來統一管理：
示例：使用 Spring 的 OncePerRequestFilter
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.web.filter.OncePerRequestFilter;
publicclass TraceIdFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain)
throws ServletException, IOException {
String traceId = request.getHeader("X-Trace-Id");
if (traceId == null || traceId.isEmpty()) {
traceId = UUID.randomUUID().toString();
}
MDC.put("traceId", traceId);
try {
filterChain.doFilter(request, response);
} finally {
MDC.remove("traceId");
}
}
}將該過濾器注冊到 Spring 容器中即可。
四、示例代碼
1. 過濾器類
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.UUID;
publicclass TraceIdFilter extends OncePerRequestFilter {
privatestaticfinal String TRACE_ID_HEADER = "X-Trace-Id";
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain)
throws ServletException, IOException {
String traceId = request.getHeader(TRACE_ID_HEADER);
if (traceId == null || traceId.isEmpty()) {
traceId = UUID.randomUUID().toString();
}
MDC.put("traceId", traceId);
try {
filterChain.doFilter(request, response);
} finally {
MDC.remove("traceId");
}
}
}2. Spring Boot 中注冊過濾器
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
@Configuration
publicclass WebConfig {
@Bean
public FilterRegistrationBean<TraceIdFilter> traceIdFilter() {
FilterRegistrationBean<TraceIdFilter> registrationBean = new FilterRegistrationBean<>();
registrationBean.setFilter(new TraceIdFilter());
registrationBean.addUrlPatterns("/*"); // 過濾所有請求
registrationBean.setOrder(1); // 優先級
return registrationBean;
}
}3. 日志配置（logback.xml）
<configuration>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>[%d{yyyy-MM-dd HH:mm:ss}] [traceId:%X{traceId}] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<root level="info">
<appender-ref ref="STDOUT" />
</root>
</configuration>五、注意事項
在使用一項技術或者一個框架時，我們都需要知道有什么弊端，這樣才能更好的幫助我們做好技術決策，下面是使用MDC需要注意的事項：
- 線程安全：在多線程環境下，確保 MDC 的設置和清理，以避免 traceId 泄漏到其他線程。
- 性能影響：頻繁操作 MDC 可能略微影響性能，需權衡日志詳細程度和性能需求。
- 日志存儲：確保日志存儲系統支持和索引 traceId，以便高效查詢和分析。
- 異常處理：在異常情況下，確保 traceId 仍能正確記錄在日志中，有助于快速定位問題。
六、總結
本文，我們分析了如何使用MDC實現全鏈路追蹤，通過合理使用 SLF4J的MDC，可以在分布式系統中實現全鏈路的 traceId 追蹤，提升日志的可讀性和追蹤能力。但是，對于更復雜的需求，我們還是建議結合專門的分布式追蹤工具，比如 Spring Cloud Sleuth、Zipkin 或 Jaeger，以獲得更全面的追蹤能力。
責任編輯：趙寧寧
來源：
猿java
