透傳)
1. 項(xiàng)目概述為什么我們需要一個(gè)貫穿始終的logId在分布式系統(tǒng)或者一個(gè)稍具規(guī)模的單體應(yīng)用中排查一個(gè)用戶請求的完整軌跡常常像在玩一個(gè)沒有地圖的尋寶游戲。你可能會在網(wǎng)關(guān)日志里看到請求A在業(yè)務(wù)服務(wù)B的日志里看到一段相關(guān)處理又在數(shù)據(jù)庫慢查詢?nèi)罩纠锇l(fā)現(xiàn)一條可疑記錄但你怎么能百分之百確定它們屬于同一次用戶操作傳統(tǒng)的日志記錄方式依賴時(shí)間戳和線程名在低并發(fā)下或許可行一旦流量上來各種異步處理、線程池復(fù)用日志就會混雜在一起難以梳理。這就是引入“l(fā)ogId”或稱為traceId、requestId的唯一標(biāo)識的價(jià)值所在。它的核心目標(biāo)是為同一次業(yè)務(wù)請求在所有涉及的系統(tǒng)、服務(wù)、線程中打上同一個(gè)“身份證號”。無論這個(gè)請求經(jīng)歷了多少層調(diào)用、跨了多少個(gè)服務(wù)、被多少個(gè)線程處理過只要日志中攜帶了這個(gè)logId我們就能像用一根線串起散落的珍珠一樣快速、準(zhǔn)確地還原出這次請求的完整生命周期和調(diào)用鏈路。最近的一些事件比如某些服務(wù)提示“請求過多”或“處理請求時(shí)遇到錯(cuò)誤”如果日志中沒有全局唯一的請求標(biāo)識開發(fā)人員定位問題就如同大海撈針無法快速判斷是用戶頻繁操作、網(wǎng)絡(luò)重試導(dǎo)致的重復(fù)請求還是服務(wù)內(nèi)部某個(gè)環(huán)節(jié)出了問題。配置Log4j2來自動生成和傳遞logId就是為了從根本上解決這種可觀測性的痛點(diǎn)讓日志從雜亂的信息記錄變成可追蹤、可分析的診斷工具。2. 核心設(shè)計(jì)思路與方案選型為請求配置唯一logId聽起來簡單但實(shí)現(xiàn)起來需要考慮整個(gè)請求生命周期的上下文管理。核心思路可以概括為“源頭生成全程攜帶日志集成”。2.1 方案對比ThreadLocal vs MDC在Java生態(tài)中實(shí)現(xiàn)請求上下文傳遞主要有兩大陣營ThreadLocal和 Log4j2自帶的ThreadContext通常通過其門面類MDC使用。ThreadLocal方案 這是最基礎(chǔ)也最靈活的方案。你可以在過濾器或攔截器中生成一個(gè)UUID存入一個(gè)自定義的ThreadLocal變量中。在任何需要的地方通過ThreadLocal.get()來獲取。它的優(yōu)點(diǎn)是概念清晰完全受控。但缺點(diǎn)也很明顯內(nèi)存泄漏風(fēng)險(xiǎn)如果使用不當(dāng)尤其是配合線程池時(shí)忘記在請求處理完畢后remove()會造成嚴(yán)重的內(nèi)存泄漏。上下文傳遞困難當(dāng)請求處理涉及異步操作如Async、CompletableFuture或切換到子線程時(shí)ThreadLocal的值不會自動繼承需要手動傳遞增加了代碼的復(fù)雜性和出錯(cuò)概率。MDCMapped Diagnostic Context方案 MDC是SLF4J提供、Log4j2實(shí)現(xiàn)的一個(gè)診斷上下文工具。它本質(zhì)上是一個(gè)與當(dāng)前線程綁定的Map。相比原生ThreadLocalMDC方案與日志框架天生集成是完成我們目標(biāo)的更優(yōu)選擇理由如下日志框架原生支持在Log4j2的PatternLayout中可以直接通過%X{key}來輸出MDC中存儲的值集成成本極低。設(shè)計(jì)更完善MDC內(nèi)部已經(jīng)考慮了線程池等場景的一些基礎(chǔ)處理盡管在異步場景下仍需額外處理但有現(xiàn)成的解決方案如ThreadContext的Stack和CloseableThreadContext。生態(tài)兼容性好作為SLF4J的標(biāo)準(zhǔn)各種中間件、監(jiān)控組件如SkyWalking, Zipkin都對其有良好支持便于未來擴(kuò)展。實(shí)操心得在幾年前我可能會為了極致控制而選擇ThreadLocal。但現(xiàn)在對于日志追蹤這個(gè)特定場景MDC是毫無疑問的首選。它減少了我們自己造輪子的風(fēng)險(xiǎn)并且能讓日志配置變得異常簡潔。除非有非常特殊的、MDC無法滿足的上下文管理需求否則都應(yīng)優(yōu)先采用MDC方案。2.2 整體架構(gòu)設(shè)計(jì)我們的目標(biāo)架構(gòu)非常清晰生成與注入在請求進(jìn)入應(yīng)用的第一時(shí)間通常是一個(gè)Servlet Filter或Spring Interceptor生成一個(gè)全局唯一的logId例如UUID并將其放入MDC或Log4j2的ThreadContext中。透傳與繼承確保在處理請求的整個(gè)過程中包括同步調(diào)用、異步方法、跨服務(wù)調(diào)用通過HTTP頭或RPC上下文這個(gè)logId都能被正確傳遞。日志輸出在Log4j2的日志輸出模式Pattern中配置一個(gè)占位符如%X{logId}讓每一條日志自動附帶這個(gè)logId。清理在請求處理結(jié)束時(shí)清理MDC中的logId避免污染后續(xù)請求特別是在使用線程池時(shí)。這個(gè)流程確保了從控制器、服務(wù)層、數(shù)據(jù)訪問層甚至到某個(gè)工具類中打的日志只要屬于同一個(gè)請求就會帶有相同的logId。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 LogId的生成策略與考量生成一個(gè)唯一ID聽起來用UUID.randomUUID().toString()就夠了但在高并發(fā)、分布式場景下我們還需要考慮更多。UUID最通用的選擇UUID.randomUUID()生成36位字符串含連字符全球唯一。優(yōu)點(diǎn)是無需中心化協(xié)調(diào)生成簡單。缺點(diǎn)是字符串較長存儲和傳輸有開銷且無序不利于數(shù)據(jù)庫索引。雪花算法Snowflake生成的是64位的長整型數(shù)字包含時(shí)間戳、工作機(jī)器ID、序列號等信息。優(yōu)點(diǎn)是趨勢遞增、數(shù)字類型存儲空間小、查詢效率高。缺點(diǎn)是需要配置機(jī)器ID在容器化動態(tài)伸縮環(huán)境中需要借助外部系統(tǒng)如Redis、ZooKeeper來管理機(jī)器ID。納秒時(shí)間戳隨機(jī)數(shù)/序列號可以自定義更短、更可讀的格式例如20250320143015987_abc12時(shí)間戳隨機(jī)串。可控性強(qiáng)但需自己保證集群內(nèi)的唯一性。對于絕大多數(shù)Web應(yīng)用如果logId主要用于日志串聯(lián)不直接作為數(shù)據(jù)庫主鍵使用UUID足矣。為了便于閱讀和傳輸通常會去掉連字符生成一個(gè)32位的字符串。import org.slf4j.MDC; import java.util.UUID; public class LogIdUtil { public static final String LOG_ID_KEY logId; /** * 生成一個(gè)簡化的UUID作為logId (32位十六進(jìn)制數(shù)字) */ public static String generateLogId() { return UUID.randomUUID().toString().replace(-, ); } /** * 將logId設(shè)置到MDC上下文中 */ public static void setLogId(String logId) { MDC.put(LOG_ID_KEY, logId); } /** * 從MDC獲取當(dāng)前l(fā)ogId */ public static String getLogId() { return MDC.get(LOG_ID_KEY); } /** * 清除MDC中的logId */ public static void clearLogId() { MDC.remove(LOG_ID_KEY); } }注意事項(xiàng)生成logId的時(shí)機(jī)要盡可能早最好是在網(wǎng)關(guān)或最外層的過濾器。如果應(yīng)用前面有Nginx等代理可以考慮從代理層傳入一個(gè)X-Request-ID頭部應(yīng)用層優(yōu)先使用它沒有則自己生成。這樣可以實(shí)現(xiàn)全鏈路的追蹤。3.2 使用Servlet Filter進(jìn)行攔截注入在基于Servlet的Java Web應(yīng)用中Filter是攔截請求的第一道關(guān)卡是放置logId注入邏輯的理想位置。import javax.servlet.*; import javax.servlet.annotation.WebFilter; import javax.servlet.http.HttpServletRequest; import java.io.IOException; import java.util.UUID; WebFilter(urlPatterns /*) // 攔截所有請求 public class LogIdFilter implements Filter { private static final String LOG_ID_HEADER X-Request-ID; private static final String LOG_ID_KEY logId; Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; String logId; // 1. 優(yōu)先嘗試從請求頭中獲取便于跨服務(wù)傳遞 logId httpRequest.getHeader(LOG_ID_HEADER); // 2. 如果請求頭中沒有則自己生成 if (logId null || logId.isBlank()) { logId UUID.randomUUID().toString().replace(-, ); } // 3. 將logId設(shè)置到MDC中 MDC.put(LOG_ID_KEY, logId); // 4. 可選將logId添加到響應(yīng)頭方便前端或下游服務(wù)查看 if (response instanceof HttpServletResponse) { ((HttpServletResponse) response).setHeader(LOG_ID_HEADER, logId); } try { // 5. 繼續(xù)執(zhí)行過濾器鏈 chain.doFilter(request, response); } finally { // 6. 【關(guān)鍵】請求處理完畢后務(wù)必清理MDC防止內(nèi)存泄漏和上下文污染 MDC.remove(LOG_ID_KEY); } } Override public void init(FilterConfig filterConfig) throws ServletException { // 初始化操作如果需要的話 } Override public void destroy() { // 銷毀操作如果需要的話 } }關(guān)鍵點(diǎn)解析try...finally塊這是保證MDC被清理的核心。無論請求處理過程中是正常返回還是拋出異常finally塊中的MDC.remove()都會執(zhí)行確保線程池中的線程在處理下一個(gè)請求時(shí)是“干凈”的。響應(yīng)頭設(shè)置將logId設(shè)置到響應(yīng)頭是一個(gè)好習(xí)慣。對于前端如果遇到錯(cuò)誤可以將這個(gè)ID反饋給用戶或技術(shù)支持便于后端快速定位日志。對于微服務(wù)調(diào)用鏈下游服務(wù)可以繼續(xù)傳遞這個(gè)ID。請求頭優(yōu)先檢查并優(yōu)先使用傳入的X-Request-ID這是實(shí)現(xiàn)跨服務(wù)鏈路追蹤的基礎(chǔ)。第一個(gè)收到請求的服務(wù)生成ID后續(xù)所有服務(wù)都透傳這個(gè)ID。3.3 在Spring Boot中通過Interceptor實(shí)現(xiàn)如果你使用的是Spring Boot使用HandlerInterceptor會更加Spring風(fēng)格并且可以更精細(xì)地控制攔截路徑如排除靜態(tài)資源。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 LogIdInterceptor implements HandlerInterceptor { private static final String LOG_ID_HEADER X-Request-ID; private static final String LOG_ID_KEY logId; Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String logId request.getHeader(LOG_ID_HEADER); if (logId null || logId.isBlank()) { logId UUID.randomUUID().toString().replace(-, ); } MDC.put(LOG_ID_KEY, logId); response.setHeader(LOG_ID_HEADER, logId); // 設(shè)置響應(yīng)頭 return true; // 繼續(xù)執(zhí)行 } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { // 請求處理完成后清理MDC MDC.remove(LOG_ID_KEY); } }然后需要通過配置類將這個(gè)攔截器注冊到Spring MVC中import org.springframework.beans.factory.annotation.Autowired; 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 { Autowired private LogIdInterceptor logIdInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(logIdInterceptor) .addPathPatterns(/**) // 攔截所有API路徑 .excludePathPatterns(/css/**, /js/**, /images/**); // 排除靜態(tài)資源 } }實(shí)操心得在Spring Boot中我更喜歡用Interceptor而非Filter。因?yàn)镮nterceptor能更自然地融入Spring生態(tài)方便獲取Spring管理的Bean也更容易通過excludePathPatterns排除一些不需要處理的請求如健康檢查端點(diǎn)/actuator/health避免產(chǎn)生不必要的日志ID。4. Log4j2配置詳解讓logId自動出現(xiàn)在每行日志前面我們成功將logId放入了MDC接下來就是配置Log4j2讓它自動將MDC中的logId打印出來。這是最關(guān)鍵的一步否則所有工作都白費(fèi)。4.1 基礎(chǔ)PatternLayout配置假設(shè)你使用的是log4j2.xml配置文件我們需要修改PatternLayout的pattern。?xml version1.0 encodingUTF-8? Configuration statusWARN Appenders !-- 控制臺輸出 -- Console nameConsole targetSYSTEM_OUT !-- 關(guān)鍵在pattern中添加 %X{logId} -- PatternLayout pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1.} - [logId:%X{logId}] - %msg%n/ /Console !-- 文件輸出同樣加上logId -- RollingFile nameRollingFile fileNamelogs/app.log filePatternlogs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz PatternLayout pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1.} - [logId:%X{logId}] - %msg%n/ Policies TimeBasedTriggeringPolicy / SizeBasedTriggeringPolicy size100 MB/ /Policies DefaultRolloverStrategy max10/ /RollingFile /Appenders Loggers Root levelinfo AppenderRef refConsole/ AppenderRef refRollingFile/ /Root /Loggers /Configuration配置解析%X{logId}這就是從MDC中取出key為logId的值的占位符。如果MDC中沒有l(wèi)ogId這里會輸出空。我們用方括號[]將它包裹起來使其在日志中更醒目。%d,%t,%level,%c,%msg是Log4j2常用的轉(zhuǎn)換符分別代表日期、線程、日志級別、Logger名和消息本身。這個(gè)配置會讓每一條日志行都自動附帶當(dāng)前的logId例如2023-10-27 14:30:25.123 [http-nio-8080-exec-1] INFO c.e.s.UserService - [logId:6b3a8c5f1d4e2a7b9c0f8e3d5a1b2c6] - 用戶登錄成功4.2 高級配置為異步日志配置ContextMap如果你的應(yīng)用使用了Log4j2的異步日志AsyncLogger或AsyncRoot需要特別注意。在異步記錄時(shí)日志事件可能是在另一個(gè)線程中被處理的。為了確保MDC上下文能正確地從生產(chǎn)日志的線程傳遞到消費(fèi)日志的線程我們需要在配置中啟用includeThreadContext。Configuration statusWARN Appenders Console nameConsole targetSYSTEM_OUT PatternLayout pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1.} - [logId:%X{logId}] - %msg%n/ /Console /Appenders Loggers !-- 使用 AsyncLogger 并設(shè)置 includeThreadContexttrue -- AsyncLogger namecom.example levelinfo includeThreadContexttrue AppenderRef refConsole/ /AsyncLogger AsyncRoot levelinfo includeThreadContexttrue AppenderRef refConsole/ /AsyncRoot /Loggers /Configuration將includeThreadContext設(shè)置為true默認(rèn)就是true但顯式聲明是個(gè)好習(xí)慣Log4j2在將日志事件放入異步隊(duì)列時(shí)會捕獲當(dāng)前線程的MDC上下文快照并在異步線程中處理日志時(shí)恢復(fù)它。這樣即使在異步日志中%X{logId}也能正確輸出。4.3 配置logId的默認(rèn)值有時(shí)在一些非Web請求的上下文中如定時(shí)任務(wù)、消息隊(duì)列監(jiān)聽器MDC中可能沒有l(wèi)ogId這會導(dǎo)致日志中[logId:]后面為空不太美觀。我們可以通過Log4j2的MapLookup或自定義Lookup來設(shè)置一個(gè)默認(rèn)值但更簡單的方法是在Pattern中使用條件判斷。Log4j2的Pattern支持簡單的條件語法。我們可以這樣配置當(dāng)MDC中沒有l(wèi)ogId時(shí)輸出“N/A”或一個(gè)固定標(biāo)識PatternLayout pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1.} - [logId:%X{logId:-N/A}] - %msg%n/看就是在%X{logId}后面加了一個(gè):-N/A。這表示如果%X{logId}為空則默認(rèn)輸出“N/A”。這個(gè)語法非常實(shí)用。5. 處理異步與多線程場景下的logId傳遞這是實(shí)現(xiàn)全局logId最具挑戰(zhàn)性的部分。在Web請求的同步處理中MDC工作得很好因?yàn)檎麄€(gè)過程都在同一個(gè)線程。但一旦涉及異步編程線程切換會導(dǎo)致ThreadLocalMDC的底層實(shí)現(xiàn)存儲的上下文丟失。5.1 使用Spring的Async注解當(dāng)你在Service層的一個(gè)方法上標(biāo)注了AsyncSpring會使用一個(gè)線程池來執(zhí)行這個(gè)方法。此時(shí)執(zhí)行異步方法的線程與原請求線程不同MDC上下文不會自動傳遞。解決方案配置一個(gè)TaskDecoratorSpring的ThreadPoolTaskExecutor允許我們設(shè)置一個(gè)TaskDecorator它可以在任務(wù)執(zhí)行前后進(jìn)行裝飾我們可以在這里進(jìn)行MDC上下文的傳遞。import org.slf4j.MDC; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.task.TaskDecorator; import org.springframework.scheduling.annotation.AsyncConfigurerSupport; import org.springframework.scheduling.annotation.EnableAsync; import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor; import java.util.Map; import java.util.concurrent.Executor; Configuration EnableAsync public class AsyncConfig extends AsyncConfigurerSupport { Override Bean(name taskExecutor) public Executor getAsyncExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(5); executor.setMaxPoolSize(10); executor.setQueueCapacity(25); executor.setThreadNamePrefix(Async-); // 關(guān)鍵設(shè)置TaskDecorator來傳遞MDC上下文 executor.setTaskDecorator(new MdcTaskDecorator()); executor.initialize(); return executor; } /** * 任務(wù)裝飾器用于復(fù)制MDC上下文到異步線程 */ static class MdcTaskDecorator implements TaskDecorator { Override public Runnable decorate(Runnable runnable) { // 獲取當(dāng)前線程提交任務(wù)的線程的MDC上下文快照 MapString, String contextMap MDC.getCopyOfContextMap(); return () - { try { // 異步任務(wù)執(zhí)行前將MDC上下文設(shè)置到新線程中 if (contextMap ! null) { MDC.setContextMap(contextMap); } // 執(zhí)行原始任務(wù) runnable.run(); } finally { // 異步任務(wù)執(zhí)行后清理新線程的MDC上下文 MDC.clear(); } }; } } }這樣配置后所有通過Async執(zhí)行的異步方法其日志都會自動攜帶調(diào)用者線程的logId。5.2 使用CompletableFuture如果你直接使用CompletableFuture.supplyAsync()等靜態(tài)方法它使用的是ForkJoinPool公共池同樣需要手動傳遞上下文。import org.slf4j.MDC; import java.util.Map; import java.util.concurrent.CompletableFuture; public class SomeService { public CompletableFutureString asyncProcess() { // 1. 在調(diào)用異步方法前先獲取當(dāng)前MDC上下文 MapString, String contextMap MDC.getCopyOfContextMap(); // 2. 在異步任務(wù)中恢復(fù)上下文 return CompletableFuture.supplyAsync(() - { if (contextMap ! null) { MDC.setContextMap(contextMap); } try { // 你的異步業(yè)務(wù)邏輯 logger.info(在異步任務(wù)中處理...); // 這條日志會帶有l(wèi)ogId return 處理結(jié)果; } finally { MDC.clear(); } }); } }5.3 使用Log4j2的CloseableThreadContext推薦對于更復(fù)雜的場景或者不想深度耦合Spring的TaskDecoratorLog4j2自身提供了一個(gè)更優(yōu)雅的工具CloseableThreadContext。它不僅可以管理MDC還可以管理NDC嵌套診斷上下文。你可以在開啟異步任務(wù)的地方使用CloseableThreadContext來包裝任務(wù)import org.apache.logging.log4j.CloseableThreadContext; import org.apache.logging.log4j.ThreadContext; import java.util.concurrent.CompletableFuture; public class SomeService { public CompletableFutureString asyncProcessWithLog4j2() { // 獲取當(dāng)前所有的ThreadContext包括MDC數(shù)據(jù) // 注意這里使用Log4j2原生的ThreadContext而不是SLF4J的MDC // 因?yàn)镾LF4J的MDC底層就是由Log4j2的ThreadContext實(shí)現(xiàn)的所以數(shù)據(jù)是相通的 // 但為了保險(xiǎn)我們直接使用Log4j2的API來捕獲 MapString, String context ThreadContext.getImmutableContext(); return CompletableFuture.supplyAsync(() - { // 使用CloseableThreadContext.Instance將上下文注入新線程 // try-with-resources語法確保最后自動清理 try (CloseableThreadContext.Instance ctc CloseableThreadContext.putAll(context)) { // 此時(shí)新線程的ThreadContextMDC已經(jīng)包含了原線程的所有內(nèi)容 logger.info(使用CloseableThreadContext的異步任務(wù)...); return 處理結(jié)果; } // 離開try塊后上下文會自動被清理 }); } }CloseableThreadContext.putAll(context)方法會將傳入的Map中的所有鍵值對放入新線程的上下文中并且返回的CloseableThreadContext.Instance是一個(gè)AutoCloseable在try-with-resources塊結(jié)束時(shí)會自動清理它本次添加的所有上下文而不會影響其他可能存在的上下文非常安全。踩坑記錄曾經(jīng)在一個(gè)項(xiàng)目中我們混合使用了Async和手動CompletableFuture但沒有統(tǒng)一處理上下文傳遞導(dǎo)致日志中的logId時(shí)有時(shí)無排查問題極其痛苦。后來我們強(qiáng)制規(guī)定所有異步操作必須通過統(tǒng)一的、裝飾了TaskDecorator的線程池執(zhí)行或者使用CloseableThreadContext包裝問題才得以根治。一致性是分布式追蹤的生命線。6. 微服務(wù)場景下的logId透傳在微服務(wù)架構(gòu)中一個(gè)用戶請求會經(jīng)過網(wǎng)關(guān)、多個(gè)業(yè)務(wù)服務(wù)、數(shù)據(jù)庫、緩存等。要讓logId貫穿整條調(diào)用鏈需要在服務(wù)間調(diào)用時(shí)進(jìn)行透傳。6.1 HTTP調(diào)用透傳使用RestTemplate或Feign使用RestTemplate你可以通過自定義ClientHttpRequestInterceptor在發(fā)送請求前將logId添加到HTTP頭中。import org.slf4j.MDC; import org.springframework.http.HttpRequest; import org.springframework.http.client.ClientHttpRequestExecution; import org.springframework.http.client.ClientHttpRequestInterceptor; import org.springframework.http.client.ClientHttpResponse; import java.io.IOException; Component public class LogIdRestTemplateInterceptor implements ClientHttpRequestInterceptor { private static final String LOG_ID_HEADER X-Request-ID; Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { String logId MDC.get(logId); if (logId ! null !logId.isBlank()) { request.getHeaders().add(LOG_ID_HEADER, logId); } return execution.execute(request, body); } }然后將這個(gè)攔截器配置到你使用的RestTemplateBean中。使用OpenFeignFeign可以通過自定義RequestInterceptor來實(shí)現(xiàn)同樣的功能。import feign.RequestInterceptor; import feign.RequestTemplate; import org.slf4j.MDC; import org.springframework.stereotype.Component; Component public class LogIdFeignInterceptor implements RequestInterceptor { private static final String LOG_ID_HEADER X-Request-ID; Override public void apply(RequestTemplate template) { String logId MDC.get(logId); if (logId ! null !logId.isBlank()) { template.header(LOG_ID_HEADER, logId); } } }只要這個(gè)Interceptor被Spring管理它就會自動應(yīng)用于所有的Feign客戶端。6.2 RPC框架透傳以Dubbo為例對于Dubbo這樣的RPC框架可以通過org.apache.dubbo.rpc.Filter來實(shí)現(xiàn)上下文的透傳。import org.apache.dubbo.common.constants.CommonConstants; import org.apache.dubbo.common.extension.Activate; import org.apache.dubbo.rpc.*; import org.slf4j.MDC; Activate(group {CommonConstants.PROVIDER, CommonConstants.CONSUMER}) public class LogIdDubboFilter implements Filter { private static final String LOG_ID_KEY logId; private static final String DUBBO_LOG_ID_KEY dubboLogId; // 用于在Dubbo Attachment中傳遞的key Override public Result invoke(Invoker? invoker, Invocation invocation) throws RpcException { // 消費(fèi)者端將MDC中的logId放入RPC上下文中 if (RpcContext.getContext().isConsumerSide()) { String logId MDC.get(LOG_ID_KEY); if (logId ! null) { invocation.setAttachment(DUBBO_LOG_ID_KEY, logId); } } // 提供者端從RPC上下文中取出logId并設(shè)置到MDC中 if (RpcContext.getContext().isProviderSide()) { String logId invocation.getAttachment(DUBBO_LOG_ID_KEY); if (logId ! null !logId.isBlank()) { MDC.put(LOG_ID_KEY, logId); } else { // 如果沒有傳遞可以生成一個(gè)但最好保持鏈路一致這里生成可能會破壞鏈路 // MDC.put(LOG_ID_KEY, generateLogId()); } } try { return invoker.invoke(invocation); } finally { // 提供者端調(diào)用結(jié)束后清理MDC if (RpcContext.getContext().isProviderSide()) { MDC.remove(LOG_ID_KEY); } } } }還需要在src/main/resources/META-INF/dubbo目錄下創(chuàng)建org.apache.dubbo.rpc.Filter文件內(nèi)容為logIdFiltercom.yourpackage.LogIdDubboFilter6.3 消息隊(duì)列場景透傳當(dāng)服務(wù)通過消息隊(duì)列如RabbitMQ、Kafka進(jìn)行異步通信時(shí)也需要將logId放在消息頭中傳遞。以Spring AMQP (RabbitMQ)為例發(fā)送消息時(shí)import org.springframework.amqp.core.Message; import org.springframework.amqp.core.MessageBuilder; import org.springframework.amqp.core.MessageProperties; import org.slf4j.MDC; public void sendMessage(String routingKey, Object payload) { String logId MDC.get(logId); Message message MessageBuilder.withBody(objectMapper.writeValueAsBytes(payload)) .setContentType(MessageProperties.CONTENT_TYPE_JSON) .setHeader(X-Request-ID, logId) // 將logId放入消息頭 .build(); rabbitTemplate.convertAndSend(exchangeName, routingKey, message); }消費(fèi)消息時(shí)在監(jiān)聽器方法中先從消息頭中取出logId并設(shè)置到MDC。import org.springframework.amqp.core.Message; import org.springframework.amqp.rabbit.annotation.RabbitListener; import org.slf4j.MDC; import org.slf4j.Logger; import org.slf4j.LoggerFactory; Component public class MyMessageListener { private static final Logger logger LoggerFactory.getLogger(MyMessageListener.class); RabbitListener(queues your.queue) public void handleMessage(Message message, Payload YourBusinessObject payload) { String logId null; try { // 從消息頭中獲取logId MessageProperties properties message.getMessageProperties(); if (properties ! null properties.getHeaders() ! null) { logId (String) properties.getHeaders().get(X-Request-ID); } // 如果消息中沒有可以生成一個(gè)新的但建議傳遞以保證鏈路完整 if (logId null) { logId MQ- UUID.randomUUID().toString().replace(-, ).substring(0, 16); } MDC.put(logId, logId); logger.info(開始處理消息消息ID: {}, properties.getMessageId()); // ... 你的業(yè)務(wù)邏輯 logger.info(消息處理完成); } catch (Exception e) { logger.error(處理消息失敗, e); } finally { // 務(wù)必清理MDC MDC.remove(logId); } } }注意事項(xiàng)在消息隊(duì)列場景中一個(gè)生產(chǎn)請求可能觸發(fā)多個(gè)消息進(jìn)而被多個(gè)消費(fèi)者處理。此時(shí)這幾個(gè)消費(fèi)者處理的日志會共享同一個(gè)logId。這既是優(yōu)點(diǎn)可以追蹤整個(gè)業(yè)務(wù)流也可能帶來混淆多個(gè)并行處理共享ID。需要根據(jù)業(yè)務(wù)語義判斷是否合適。對于完全獨(dú)立的并行任務(wù)有時(shí)生成子ID如parentLogId-childId會更清晰。7. 常見問題排查與實(shí)戰(zhàn)技巧即使配置看起來完美在實(shí)際運(yùn)行中還是會遇到各種“詭異”的問題。下面是我在多次實(shí)踐中總結(jié)的常見坑點(diǎn)和解決技巧。7.1 問題排查速查表問題現(xiàn)象可能原因排查步驟與解決方案日志中[logId:]為空1. Filter/Interceptor未生效或路徑不匹配。2. 在設(shè)置MDC之前就打印了日志。3. 使用了異步日志但未配置includeThreadContexttrue。1. 檢查Filter/Interceptor的注冊路徑確認(rèn)其能攔截到目標(biāo)請求。2. 確保在請求處理的最早期如Filter的doFilter開頭設(shè)置MDC。3. 檢查Log4j2配置為AsyncLogger/Root添加includeThreadContexttrue。異步任務(wù)中l(wèi)ogId丟失1. 未使用TaskDecorator或CloseableThreadContext傳遞上下文。2. 自定義線程池未處理上下文傳遞。1. 為Async使用的線程池配置TaskDecorator。2. 對于手動創(chuàng)建的線程或線程池使用CloseableThreadContext包裝Runnable任務(wù)。微服務(wù)調(diào)用鏈logId中斷1. HTTP/RPC客戶端未添加攔截器來傳遞請求頭。2. 服務(wù)端未從請求頭中讀取并設(shè)置到MDC。3. 網(wǎng)關(guān)未生成或轉(zhuǎn)發(fā)X-Request-ID。1. 檢查RestTemplate/Feign/Dubbo的攔截器配置是否正確加載。2. 確保服務(wù)端的Filter/Interceptor能正確讀取約定的請求頭如X-Request-ID。3. 在網(wǎng)關(guān)層如Spring Cloud Gateway, Nginx統(tǒng)一生成和轉(zhuǎn)發(fā)請求ID。定時(shí)任務(wù)等非請求場景無logId定時(shí)任務(wù)、命令行程序等沒有HTTP請求入口因此Filter/Interceptor不會執(zhí)行。1. 在定時(shí)任務(wù)的run方法開始時(shí)手動生成并設(shè)置一個(gè)logId到MDC。2. 使用try...finally確保任務(wù)結(jié)束后清理MDC。logId在異常堆棧中不顯示異常打印時(shí)默認(rèn)的e.printStackTrace()或日志框架的異常輸出不包含MDC信息。確保使用日志框架如logger.error(錯(cuò)誤信息, e)來記錄異常這樣異常信息會和帶有l(wèi)ogId的日志行關(guān)聯(lián)。PatternLayout中的%xEx或%throwable轉(zhuǎn)換符可以輸出異常。高并發(fā)下logId串號1. 線程池復(fù)用線程MDC未清理干凈。2. 在finally塊中清理MDC的代碼未執(zhí)行如線程被強(qiáng)制中斷。1.絕對保證在請求處理結(jié)束的finally塊中調(diào)用MDC.clear()或MDC.remove(logId)。2. 審查代碼避免在finally塊之前有System.exit()或無限循環(huán)導(dǎo)致無法清理。7.2 實(shí)戰(zhàn)技巧與心得為logId添加前綴以區(qū)分來源在復(fù)雜的系統(tǒng)中日志可能來自網(wǎng)關(guān)、不同服務(wù)、定時(shí)任務(wù)?？梢栽趌ogId前加一個(gè)簡短前綴如GW-網(wǎng)關(guān)、US-用戶服務(wù)、JOB-定時(shí)任務(wù)這樣在日志聚合平臺如ELK中一眼就能看出日志來源。將logId返回給前端對于API請求可以將logId放在HTTP響應(yīng)頭如X-Request-ID或JSON響應(yīng)體的一個(gè)字段中。當(dāng)用戶報(bào)告錯(cuò)誤時(shí)讓他們提供這個(gè)ID能極大提升排查效率。前端在遇到錯(cuò)誤時(shí)也可以自動在錯(cuò)誤彈窗中展示這個(gè)ID。在日志聚合平臺中利用logId如果你使用ELKElasticsearch, Logstash, Kibana或Graylog可以將logId作為一個(gè)獨(dú)立的字段進(jìn)行索引。這樣在Kibana中你可以直接搜索某個(gè)特定的logId瞬間看到這次請求在所有微服務(wù)中產(chǎn)生的所有日志實(shí)現(xiàn)真正的分布式追蹤。小心MDC的內(nèi)存泄漏這是老生常談但至關(guān)重要的一點(diǎn)。ThreadLocalMDC的基石在線程池場景下是內(nèi)存泄漏的重災(zāi)區(qū)。務(wù)必、務(wù)必、務(wù)必在try...finally的finally塊中清理。一個(gè)檢查方法是監(jiān)控你的應(yīng)用線程數(shù)如果線程數(shù)穩(wěn)定但內(nèi)存持續(xù)增長就要懷疑MDC清理的問題。考慮使用更專業(yè)的分布式追蹤系統(tǒng)對于大型微服務(wù)系統(tǒng)手動管理logId透傳會變得繁瑣且容易出錯(cuò)。此時(shí)應(yīng)考慮引入專業(yè)的APM應(yīng)用性能管理工具如SkyWalking、Zipkin或Jaeger。它們通過字節(jié)碼增強(qiáng)或探針的方式自動完成鏈路追蹤、上下文傳遞和性能監(jiān)控功能遠(yuǎn)比一個(gè)簡單的logId強(qiáng)大。你的logId可以作為這些系統(tǒng)的TraceId的一部分實(shí)現(xiàn)平滑過渡。配置Log4j2的logId看似是一個(gè)簡單的日志格式調(diào)整實(shí)則是構(gòu)建可觀測性系統(tǒng)的基石。它強(qiáng)迫我們以“請求鏈路”的視角來思考日志記錄而不是孤立地看待每一條日志信息。從Filter中那幾行簡單的MDC.put()和MDC.remove()開始到處理異步、跨服務(wù)調(diào)用這些復(fù)雜場景每一步都是在為快速定位線上問題、理解系統(tǒng)行為鋪平道路。當(dāng)你第一次通過一個(gè)logId在幾秒鐘內(nèi)從數(shù)千萬條日志中精準(zhǔn)拉出某個(gè)用戶失敗請求的完整軌跡時(shí)你就會覺得這一切的配置和踩坑都是值得的。 Log4j2全局logId配置指南：從MDC到異步與微服務(wù)透傳
1. 項(xiàng)目概述為什么我們需要一個(gè)貫穿始終的logId在分布式系統(tǒng)或者一個(gè)稍具規(guī)模的單體應(yīng)用中排查一個(gè)用戶請求的完整軌跡常常像在玩一個(gè)沒有地圖的尋寶游戲。你可能會在網(wǎng)關(guān)日志里看到請求A在業(yè)務(wù)服務(wù)B的日志里看到一段相關(guān)處理又在數(shù)據(jù)庫慢查詢?nèi)罩纠锇l(fā)現(xiàn)一條可疑記錄但你怎么能百分之百確定它們屬于同一次用戶操作傳統(tǒng)的日志記錄方式依賴時(shí)間戳和線程名在低并發(fā)下或許可行一旦流量上來各種異步處理、線程池復(fù)用日志就會混雜在一起難以梳理。這就是引入“l(fā)ogId”或稱為traceId、requestId的唯一標(biāo)識的價(jià)值所在。它的核心目標(biāo)是為同一次業(yè)務(wù)請求在所有涉及的系統(tǒng)、服務(wù)、線程中打上同一個(gè)“身份證號”。無論這個(gè)請求經(jīng)歷了多少層調(diào)用、跨了多少個(gè)服務(wù)、被多少個(gè)線程處理過只要日志中攜帶了這個(gè)logId我們就能像用一根線串起散落的珍珠一樣快速、準(zhǔn)確地還原出這次請求的完整生命周期和調(diào)用鏈路。最近的一些事件比如某些服務(wù)提示“請求過多”或“處理請求時(shí)遇到錯(cuò)誤”如果日志中沒有全局唯一的請求標(biāo)識開發(fā)人員定位問題就如同大海撈針無法快速判斷是用戶頻繁操作、網(wǎng)絡(luò)重試導(dǎo)致的重復(fù)請求還是服務(wù)內(nèi)部某個(gè)環(huán)節(jié)出了問題。配置Log4j2來自動生成和傳遞logId就是為了從根本上解決這種可觀測性的痛點(diǎn)讓日志從雜亂的信息記錄變成可追蹤、可分析的診斷工具。2. 核心設(shè)計(jì)思路與方案選型為請求配置唯一logId聽起來簡單但實(shí)現(xiàn)起來需要考慮整個(gè)請求生命周期的上下文管理。核心思路可以概括為“源頭生成全程攜帶日志集成”。2.1 方案對比ThreadLocal vs MDC在Java生態(tài)中實(shí)現(xiàn)請求上下文傳遞主要有兩大陣營ThreadLocal和 Log4j2自帶的ThreadContext通常通過其門面類MDC使用。ThreadLocal方案 這是最基礎(chǔ)也最靈活的方案。你可以在過濾器或攔截器中生成一個(gè)UUID存入一個(gè)自定義的ThreadLocal變量中。在任何需要的地方通過ThreadLocal.get()來獲取。它的優(yōu)點(diǎn)是概念清晰完全受控。但缺點(diǎn)也很明顯內(nèi)存泄漏風(fēng)險(xiǎn)如果使用不當(dāng)尤其是配合線程池時(shí)忘記在請求處理完畢后remove()會造成嚴(yán)重的內(nèi)存泄漏。上下文傳遞困難當(dāng)請求處理涉及異步操作如Async、CompletableFuture或切換到子線程時(shí)ThreadLocal的值不會自動繼承需要手動傳遞增加了代碼的復(fù)雜性和出錯(cuò)概率。MDCMapped Diagnostic Context方案 MDC是SLF4J提供、Log4j2實(shí)現(xiàn)的一個(gè)診斷上下文工具。它本質(zhì)上是一個(gè)與當(dāng)前線程綁定的Map。相比原生ThreadLocalMDC方案與日志框架天生集成是完成我們目標(biāo)的更優(yōu)選擇理由如下日志框架原生支持在Log4j2的PatternLayout中可以直接通過%X{key}來輸出MDC中存儲的值集成成本極低。設(shè)計(jì)更完善MDC內(nèi)部已經(jīng)考慮了線程池等場景的一些基礎(chǔ)處理盡管在異步場景下仍需額外處理但有現(xiàn)成的解決方案如ThreadContext的Stack和CloseableThreadContext。生態(tài)兼容性好作為SLF4J的標(biāo)準(zhǔn)各種中間件、監(jiān)控組件如SkyWalking, Zipkin都對其有良好支持便于未來擴(kuò)展。實(shí)操心得在幾年前我可能會為了極致控制而選擇ThreadLocal。但現(xiàn)在對于日志追蹤這個(gè)特定場景MDC是毫無疑問的首選。它減少了我們自己造輪子的風(fēng)險(xiǎn)并且能讓日志配置變得異常簡潔。除非有非常特殊的、MDC無法滿足的上下文管理需求否則都應(yīng)優(yōu)先采用MDC方案。2.2 整體架構(gòu)設(shè)計(jì)我們的目標(biāo)架構(gòu)非常清晰生成與注入在請求進(jìn)入應(yīng)用的第一時(shí)間通常是一個(gè)Servlet Filter或Spring Interceptor生成一個(gè)全局唯一的logId例如UUID并將其放入MDC或Log4j2的ThreadContext中。透傳與繼承確保在處理請求的整個(gè)過程中包括同步調(diào)用、異步方法、跨服務(wù)調(diào)用通過HTTP頭或RPC上下文這個(gè)logId都能被正確傳遞。日志輸出在Log4j2的日志輸出模式Pattern中配置一個(gè)占位符如%X{logId}讓每一條日志自動附帶這個(gè)logId。清理在請求處理結(jié)束時(shí)清理MDC中的logId避免污染后續(xù)請求特別是在使用線程池時(shí)。這個(gè)流程確保了從控制器、服務(wù)層、數(shù)據(jù)訪問層甚至到某個(gè)工具類中打的日志只要屬于同一個(gè)請求就會帶有相同的logId。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 LogId的生成策略與考量生成一個(gè)唯一ID聽起來用UUID.randomUUID().toString()就夠了但在高并發(fā)、分布式場景下我們還需要考慮更多。UUID最通用的選擇UUID.randomUUID()生成36位字符串含連字符全球唯一。優(yōu)點(diǎn)是無需中心化協(xié)調(diào)生成簡單。缺點(diǎn)是字符串較長存儲和傳輸有開銷且無序不利于數(shù)據(jù)庫索引。雪花算法Snowflake生成的是64位的長整型數(shù)字包含時(shí)間戳、工作機(jī)器ID、序列號等信息。優(yōu)點(diǎn)是趨勢遞增、數(shù)字類型存儲空間小、查詢效率高。缺點(diǎn)是需要配置機(jī)器ID在容器化動態(tài)伸縮環(huán)境中需要借助外部系統(tǒng)如Redis、ZooKeeper來管理機(jī)器ID。納秒時(shí)間戳隨機(jī)數(shù)/序列號可以自定義更短、更可讀的格式例如20250320143015987_abc12時(shí)間戳隨機(jī)串。可控性強(qiáng)但需自己保證集群內(nèi)的唯一性。對于絕大多數(shù)Web應(yīng)用如果logId主要用于日志串聯(lián)不直接作為數(shù)據(jù)庫主鍵使用UUID足矣。為了便于閱讀和傳輸通常會去掉連字符生成一個(gè)32位的字符串。import org.slf4j.MDC; import java.util.UUID; public class LogIdUtil { public static final String LOG_ID_KEY logId; /** * 生成一個(gè)簡化的UUID作為logId (32位十六進(jìn)制數(shù)字) */ public static String generateLogId() { return UUID.randomUUID().toString().replace(-, ); } /** * 將logId設(shè)置到MDC上下文中 */ public static void setLogId(String logId) { MDC.put(LOG_ID_KEY, logId); } /** * 從MDC獲取當(dāng)前l(fā)ogId */ public static String getLogId() { return MDC.get(LOG_ID_KEY); } /** * 清除MDC中的logId */ public static void clearLogId() { MDC.remove(LOG_ID_KEY); } }注意事項(xiàng)生成logId的時(shí)機(jī)要盡可能早最好是在網(wǎng)關(guān)或最外層的過濾器。如果應(yīng)用前面有Nginx等代理可以考慮從代理層傳入一個(gè)X-Request-ID頭部應(yīng)用層優(yōu)先使用它沒有則自己生成。這樣可以實(shí)現(xiàn)全鏈路的追蹤。3.2 使用Servlet Filter進(jìn)行攔截注入在基于Servlet的Java Web應(yīng)用中Filter是攔截請求的第一道關(guān)卡是放置logId注入邏輯的理想位置。import javax.servlet.*; import javax.servlet.annotation.WebFilter; import javax.servlet.http.HttpServletRequest; import java.io.IOException; import java.util.UUID; WebFilter(urlPatterns /*) // 攔截所有請求 public class LogIdFilter implements Filter { private static final String LOG_ID_HEADER X-Request-ID; private static final String LOG_ID_KEY logId; Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest httpRequest (HttpServletRequest) request; String logId; // 1. 優(yōu)先嘗試從請求頭中獲取便于跨服務(wù)傳遞 logId httpRequest.getHeader(LOG_ID_HEADER); // 2. 如果請求頭中沒有則自己生成 if (logId null || logId.isBlank()) { logId UUID.randomUUID().toString().replace(-, ); } // 3. 將logId設(shè)置到MDC中 MDC.put(LOG_ID_KEY, logId); // 4. 可選將logId添加到響應(yīng)頭方便前端或下游服務(wù)查看 if (response instanceof HttpServletResponse) { ((HttpServletResponse) response).setHeader(LOG_ID_HEADER, logId); } try { // 5. 繼續(xù)執(zhí)行過濾器鏈 chain.doFilter(request, response); } finally { // 6. 【關(guān)鍵】請求處理完畢后務(wù)必清理MDC防止內(nèi)存泄漏和上下文污染 MDC.remove(LOG_ID_KEY); } } Override public void init(FilterConfig filterConfig) throws ServletException { // 初始化操作如果需要的話 } Override public void destroy() { // 銷毀操作如果需要的話 } }關(guān)鍵點(diǎn)解析try...finally塊這是保證MDC被清理的核心。無論請求處理過程中是正常返回還是拋出異常finally塊中的MDC.remove()都會執(zhí)行確保線程池中的線程在處理下一個(gè)請求時(shí)是“干凈”的。響應(yīng)頭設(shè)置將logId設(shè)置到響應(yīng)頭是一個(gè)好習(xí)慣。對于前端如果遇到錯(cuò)誤可以將這個(gè)ID反饋給用戶或技術(shù)支持便于后端快速定位日志。對于微服務(wù)調(diào)用鏈下游服務(wù)可以繼續(xù)傳遞這個(gè)ID。請求頭優(yōu)先檢查并優(yōu)先使用傳入的X-Request-ID這是實(shí)現(xiàn)跨服務(wù)鏈路追蹤的基礎(chǔ)。第一個(gè)收到請求的服務(wù)生成ID后續(xù)所有服務(wù)都透傳這個(gè)ID。3.3 在Spring Boot中通過Interceptor實(shí)現(xiàn)如果你使用的是Spring Boot使用HandlerInterceptor會更加Spring風(fēng)格并且可以更精細(xì)地控制攔截路徑如排除靜態(tài)資源。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 LogIdInterceptor implements HandlerInterceptor { private static final String LOG_ID_HEADER X-Request-ID; private static final String LOG_ID_KEY logId; Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String logId request.getHeader(LOG_ID_HEADER); if (logId null || logId.isBlank()) { logId UUID.randomUUID().toString().replace(-, ); } MDC.put(LOG_ID_KEY, logId); response.setHeader(LOG_ID_HEADER, logId); // 設(shè)置響應(yīng)頭 return true; // 繼續(xù)執(zhí)行 } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { // 請求處理完成后清理MDC MDC.remove(LOG_ID_KEY); } }然后需要通過配置類將這個(gè)攔截器注冊到Spring MVC中import org.springframework.beans.factory.annotation.Autowired; 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 { Autowired private LogIdInterceptor logIdInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(logIdInterceptor) .addPathPatterns(/**) // 攔截所有API路徑 .excludePathPatterns(/css/**, /js/**, /images/**); // 排除靜態(tài)資源 } }實(shí)操心得在Spring Boot中我更喜歡用Interceptor而非Filter。因?yàn)镮nterceptor能更自然地融入Spring生態(tài)方便獲取Spring管理的Bean也更容易通過excludePathPatterns排除一些不需要處理的請求如健康檢查端點(diǎn)/actuator/health避免產(chǎn)生不必要的日志ID。4. Log4j2配置詳解讓logId自動出現(xiàn)在每行日志前面我們成功將logId放入了MDC接下來就是配置Log4j2讓它自動將MDC中的logId打印出來。這是最關(guān)鍵的一步否則所有工作都白費(fèi)。4.1 基礎(chǔ)PatternLayout配置假設(shè)你使用的是log4j2.xml配置文件我們需要修改PatternLayout的pattern。?xml version1.0 encodingUTF-8? Configuration statusWARN Appenders !-- 控制臺輸出 -- Console nameConsole targetSYSTEM_OUT !-- 關(guān)鍵在pattern中添加 %X{logId} -- PatternLayout pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1.} - [logId:%X{logId}] - %msg%n/ /Console !-- 文件輸出同樣加上logId -- RollingFile nameRollingFile fileNamelogs/app.log filePatternlogs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz PatternLayout pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1.} - [logId:%X{logId}] - %msg%n/ Policies TimeBasedTriggeringPolicy / SizeBasedTriggeringPolicy size100 MB/ /Policies DefaultRolloverStrategy max10/ /RollingFile /Appenders Loggers Root levelinfo AppenderRef refConsole/ AppenderRef refRollingFile/ /Root /Loggers /Configuration配置解析%X{logId}這就是從MDC中取出key為logId的值的占位符。如果MDC中沒有l(wèi)ogId這里會輸出空。我們用方括號[]將它包裹起來使其在日志中更醒目。%d,%t,%level,%c,%msg是Log4j2常用的轉(zhuǎn)換符分別代表日期、線程、日志級別、Logger名和消息本身。這個(gè)配置會讓每一條日志行都自動附帶當(dāng)前的logId例如2023-10-27 14:30:25.123 [http-nio-8080-exec-1] INFO c.e.s.UserService - [logId:6b3a8c5f1d4e2a7b9c0f8e3d5a1b2c6] - 用戶登錄成功4.2 高級配置為異步日志配置ContextMap如果你的應(yīng)用使用了Log4j2的異步日志AsyncLogger或AsyncRoot需要特別注意。在異步記錄時(shí)日志事件可能是在另一個(gè)線程中被處理的。為了確保MDC上下文能正確地從生產(chǎn)日志的線程傳遞到消費(fèi)日志的線程我們需要在配置中啟用includeThreadContext。Configuration statusWARN Appenders Console nameConsole targetSYSTEM_OUT PatternLayout pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1.} - [logId:%X{logId}] - %msg%n/ /Console /Appenders Loggers !-- 使用 AsyncLogger 并設(shè)置 includeThreadContexttrue -- AsyncLogger namecom.example levelinfo includeThreadContexttrue AppenderRef refConsole/ /AsyncLogger AsyncRoot levelinfo includeThreadContexttrue AppenderRef refConsole/ /AsyncRoot /Loggers /Configuration將includeThreadContext設(shè)置為true默認(rèn)就是true但顯式聲明是個(gè)好習(xí)慣Log4j2在將日志事件放入異步隊(duì)列時(shí)會捕獲當(dāng)前線程的MDC上下文快照并在異步線程中處理日志時(shí)恢復(fù)它。這樣即使在異步日志中%X{logId}也能正確輸出。4.3 配置logId的默認(rèn)值有時(shí)在一些非Web請求的上下文中如定時(shí)任務(wù)、消息隊(duì)列監(jiān)聽器MDC中可能沒有l(wèi)ogId這會導(dǎo)致日志中[logId:]后面為空不太美觀。我們可以通過Log4j2的MapLookup或自定義Lookup來設(shè)置一個(gè)默認(rèn)值但更簡單的方法是在Pattern中使用條件判斷。Log4j2的Pattern支持簡單的條件語法。我們可以這樣配置當(dāng)MDC中沒有l(wèi)ogId時(shí)輸出“N/A”或一個(gè)固定標(biāo)識PatternLayout pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1.} - [logId:%X{logId:-N/A}] - %msg%n/看就是在%X{logId}后面加了一個(gè):-N/A。這表示如果%X{logId}為空則默認(rèn)輸出“N/A”。這個(gè)語法非常實(shí)用。5. 處理異步與多線程場景下的logId傳遞這是實(shí)現(xiàn)全局logId最具挑戰(zhàn)性的部分。在Web請求的同步處理中MDC工作得很好因?yàn)檎麄€(gè)過程都在同一個(gè)線程。但一旦涉及異步編程線程切換會導(dǎo)致ThreadLocalMDC的底層實(shí)現(xiàn)存儲的上下文丟失。5.1 使用Spring的Async注解當(dāng)你在Service層的一個(gè)方法上標(biāo)注了AsyncSpring會使用一個(gè)線程池來執(zhí)行這個(gè)方法。此時(shí)執(zhí)行異步方法的線程與原請求線程不同MDC上下文不會自動傳遞。解決方案配置一個(gè)TaskDecoratorSpring的ThreadPoolTaskExecutor允許我們設(shè)置一個(gè)TaskDecorator它可以在任務(wù)執(zhí)行前后進(jìn)行裝飾我們可以在這里進(jìn)行MDC上下文的傳遞。import org.slf4j.MDC; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.task.TaskDecorator; import org.springframework.scheduling.annotation.AsyncConfigurerSupport; import org.springframework.scheduling.annotation.EnableAsync; import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor; import java.util.Map; import java.util.concurrent.Executor; Configuration EnableAsync public class AsyncConfig extends AsyncConfigurerSupport { Override Bean(name taskExecutor) public Executor getAsyncExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(5); executor.setMaxPoolSize(10); executor.setQueueCapacity(25); executor.setThreadNamePrefix(Async-); // 關(guān)鍵設(shè)置TaskDecorator來傳遞MDC上下文 executor.setTaskDecorator(new MdcTaskDecorator()); executor.initialize(); return executor; } /** * 任務(wù)裝飾器用于復(fù)制MDC上下文到異步線程 */ static class MdcTaskDecorator implements TaskDecorator { Override public Runnable decorate(Runnable runnable) { // 獲取當(dāng)前線程提交任務(wù)的線程的MDC上下文快照 MapString, String contextMap MDC.getCopyOfContextMap(); return () - { try { // 異步任務(wù)執(zhí)行前將MDC上下文設(shè)置到新線程中 if (contextMap ! null) { MDC.setContextMap(contextMap); } // 執(zhí)行原始任務(wù) runnable.run(); } finally { // 異步任務(wù)執(zhí)行后清理新線程的MDC上下文 MDC.clear(); } }; } } }這樣配置后所有通過Async執(zhí)行的異步方法其日志都會自動攜帶調(diào)用者線程的logId。5.2 使用CompletableFuture如果你直接使用CompletableFuture.supplyAsync()等靜態(tài)方法它使用的是ForkJoinPool公共池同樣需要手動傳遞上下文。import org.slf4j.MDC; import java.util.Map; import java.util.concurrent.CompletableFuture; public class SomeService { public CompletableFutureString asyncProcess() { // 1. 在調(diào)用異步方法前先獲取當(dāng)前MDC上下文 MapString, String contextMap MDC.getCopyOfContextMap(); // 2. 在異步任務(wù)中恢復(fù)上下文 return CompletableFuture.supplyAsync(() - { if (contextMap ! null) { MDC.setContextMap(contextMap); } try { // 你的異步業(yè)務(wù)邏輯 logger.info(在異步任務(wù)中處理...); // 這條日志會帶有l(wèi)ogId return 處理結(jié)果; } finally { MDC.clear(); } }); } }5.3 使用Log4j2的CloseableThreadContext推薦對于更復(fù)雜的場景或者不想深度耦合Spring的TaskDecoratorLog4j2自身提供了一個(gè)更優(yōu)雅的工具CloseableThreadContext。它不僅可以管理MDC還可以管理NDC嵌套診斷上下文。你可以在開啟異步任務(wù)的地方使用CloseableThreadContext來包裝任務(wù)import org.apache.logging.log4j.CloseableThreadContext; import org.apache.logging.log4j.ThreadContext; import java.util.concurrent.CompletableFuture; public class SomeService { public CompletableFutureString asyncProcessWithLog4j2() { // 獲取當(dāng)前所有的ThreadContext包括MDC數(shù)據(jù) // 注意這里使用Log4j2原生的ThreadContext而不是SLF4J的MDC // 因?yàn)镾LF4J的MDC底層就是由Log4j2的ThreadContext實(shí)現(xiàn)的所以數(shù)據(jù)是相通的 // 但為了保險(xiǎn)我們直接使用Log4j2的API來捕獲 MapString, String context ThreadContext.getImmutableContext(); return CompletableFuture.supplyAsync(() - { // 使用CloseableThreadContext.Instance將上下文注入新線程 // try-with-resources語法確保最后自動清理 try (CloseableThreadContext.Instance ctc CloseableThreadContext.putAll(context)) { // 此時(shí)新線程的ThreadContextMDC已經(jīng)包含了原線程的所有內(nèi)容 logger.info(使用CloseableThreadContext的異步任務(wù)...); return 處理結(jié)果; } // 離開try塊后上下文會自動被清理 }); } }CloseableThreadContext.putAll(context)方法會將傳入的Map中的所有鍵值對放入新線程的上下文中并且返回的CloseableThreadContext.Instance是一個(gè)AutoCloseable在try-with-resources塊結(jié)束時(shí)會自動清理它本次添加的所有上下文而不會影響其他可能存在的上下文非常安全。踩坑記錄曾經(jīng)在一個(gè)項(xiàng)目中我們混合使用了Async和手動CompletableFuture但沒有統(tǒng)一處理上下文傳遞導(dǎo)致日志中的logId時(shí)有時(shí)無排查問題極其痛苦。后來我們強(qiáng)制規(guī)定所有異步操作必須通過統(tǒng)一的、裝飾了TaskDecorator的線程池執(zhí)行或者使用CloseableThreadContext包裝問題才得以根治。一致性是分布式追蹤的生命線。6. 微服務(wù)場景下的logId透傳在微服務(wù)架構(gòu)中一個(gè)用戶請求會經(jīng)過網(wǎng)關(guān)、多個(gè)業(yè)務(wù)服務(wù)、數(shù)據(jù)庫、緩存等。要讓logId貫穿整條調(diào)用鏈需要在服務(wù)間調(diào)用時(shí)進(jìn)行透傳。6.1 HTTP調(diào)用透傳使用RestTemplate或Feign使用RestTemplate你可以通過自定義ClientHttpRequestInterceptor在發(fā)送請求前將logId添加到HTTP頭中。import org.slf4j.MDC; import org.springframework.http.HttpRequest; import org.springframework.http.client.ClientHttpRequestExecution; import org.springframework.http.client.ClientHttpRequestInterceptor; import org.springframework.http.client.ClientHttpResponse; import java.io.IOException; Component public class LogIdRestTemplateInterceptor implements ClientHttpRequestInterceptor { private static final String LOG_ID_HEADER X-Request-ID; Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { String logId MDC.get(logId); if (logId ! null !logId.isBlank()) { request.getHeaders().add(LOG_ID_HEADER, logId); } return execution.execute(request, body); } }然后將這個(gè)攔截器配置到你使用的RestTemplateBean中。使用OpenFeignFeign可以通過自定義RequestInterceptor來實(shí)現(xiàn)同樣的功能。import feign.RequestInterceptor; import feign.RequestTemplate; import org.slf4j.MDC; import org.springframework.stereotype.Component; Component public class LogIdFeignInterceptor implements RequestInterceptor { private static final String LOG_ID_HEADER X-Request-ID; Override public void apply(RequestTemplate template) { String logId MDC.get(logId); if (logId ! null !logId.isBlank()) { template.header(LOG_ID_HEADER, logId); } } }只要這個(gè)Interceptor被Spring管理它就會自動應(yīng)用于所有的Feign客戶端。6.2 RPC框架透傳以Dubbo為例對于Dubbo這樣的RPC框架可以通過org.apache.dubbo.rpc.Filter來實(shí)現(xiàn)上下文的透傳。import org.apache.dubbo.common.constants.CommonConstants; import org.apache.dubbo.common.extension.Activate; import org.apache.dubbo.rpc.*; import org.slf4j.MDC; Activate(group {CommonConstants.PROVIDER, CommonConstants.CONSUMER}) public class LogIdDubboFilter implements Filter { private static final String LOG_ID_KEY logId; private static final String DUBBO_LOG_ID_KEY dubboLogId; // 用于在Dubbo Attachment中傳遞的key Override public Result invoke(Invoker? invoker, Invocation invocation) throws RpcException { // 消費(fèi)者端將MDC中的logId放入RPC上下文中 if (RpcContext.getContext().isConsumerSide()) { String logId MDC.get(LOG_ID_KEY); if (logId ! null) { invocation.setAttachment(DUBBO_LOG_ID_KEY, logId); } } // 提供者端從RPC上下文中取出logId并設(shè)置到MDC中 if (RpcContext.getContext().isProviderSide()) { String logId invocation.getAttachment(DUBBO_LOG_ID_KEY); if (logId ! null !logId.isBlank()) { MDC.put(LOG_ID_KEY, logId); } else { // 如果沒有傳遞可以生成一個(gè)但最好保持鏈路一致這里生成可能會破壞鏈路 // MDC.put(LOG_ID_KEY, generateLogId()); } } try { return invoker.invoke(invocation); } finally { // 提供者端調(diào)用結(jié)束后清理MDC if (RpcContext.getContext().isProviderSide()) { MDC.remove(LOG_ID_KEY); } } } }還需要在src/main/resources/META-INF/dubbo目錄下創(chuàng)建org.apache.dubbo.rpc.Filter文件內(nèi)容為logIdFiltercom.yourpackage.LogIdDubboFilter6.3 消息隊(duì)列場景透傳當(dāng)服務(wù)通過消息隊(duì)列如RabbitMQ、Kafka進(jìn)行異步通信時(shí)也需要將logId放在消息頭中傳遞。以Spring AMQP (RabbitMQ)為例發(fā)送消息時(shí)import org.springframework.amqp.core.Message; import org.springframework.amqp.core.MessageBuilder; import org.springframework.amqp.core.MessageProperties; import org.slf4j.MDC; public void sendMessage(String routingKey, Object payload) { String logId MDC.get(logId); Message message MessageBuilder.withBody(objectMapper.writeValueAsBytes(payload)) .setContentType(MessageProperties.CONTENT_TYPE_JSON) .setHeader(X-Request-ID, logId) // 將logId放入消息頭 .build(); rabbitTemplate.convertAndSend(exchangeName, routingKey, message); }消費(fèi)消息時(shí)在監(jiān)聽器方法中先從消息頭中取出logId并設(shè)置到MDC。import org.springframework.amqp.core.Message; import org.springframework.amqp.rabbit.annotation.RabbitListener; import org.slf4j.MDC; import org.slf4j.Logger; import org.slf4j.LoggerFactory; Component public class MyMessageListener { private static final Logger logger LoggerFactory.getLogger(MyMessageListener.class); RabbitListener(queues your.queue) public void handleMessage(Message message, Payload YourBusinessObject payload) { String logId null; try { // 從消息頭中獲取logId MessageProperties properties message.getMessageProperties(); if (properties ! null properties.getHeaders() ! null) { logId (String) properties.getHeaders().get(X-Request-ID); } // 如果消息中沒有可以生成一個(gè)新的但建議傳遞以保證鏈路完整 if (logId null) { logId MQ- UUID.randomUUID().toString().replace(-, ).substring(0, 16); } MDC.put(logId, logId); logger.info(開始處理消息消息ID: {}, properties.getMessageId()); // ... 你的業(yè)務(wù)邏輯 logger.info(消息處理完成); } catch (Exception e) { logger.error(處理消息失敗, e); } finally { // 務(wù)必清理MDC MDC.remove(logId); } } }注意事項(xiàng)在消息隊(duì)列場景中一個(gè)生產(chǎn)請求可能觸發(fā)多個(gè)消息進(jìn)而被多個(gè)消費(fèi)者處理。此時(shí)這幾個(gè)消費(fèi)者處理的日志會共享同一個(gè)logId。這既是優(yōu)點(diǎn)可以追蹤整個(gè)業(yè)務(wù)流也可能帶來混淆多個(gè)并行處理共享ID。需要根據(jù)業(yè)務(wù)語義判斷是否合適。對于完全獨(dú)立的并行任務(wù)有時(shí)生成子ID如parentLogId-childId會更清晰。7. 常見問題排查與實(shí)戰(zhàn)技巧即使配置看起來完美在實(shí)際運(yùn)行中還是會遇到各種“詭異”的問題。下面是我在多次實(shí)踐中總結(jié)的常見坑點(diǎn)和解決技巧。7.1 問題排查速查表問題現(xiàn)象可能原因排查步驟與解決方案日志中[logId:]為空1. Filter/Interceptor未生效或路徑不匹配。2. 在設(shè)置MDC之前就打印了日志。3. 使用了異步日志但未配置includeThreadContexttrue。1. 檢查Filter/Interceptor的注冊路徑確認(rèn)其能攔截到目標(biāo)請求。2. 確保在請求處理的最早期如Filter的doFilter開頭設(shè)置MDC。3. 檢查Log4j2配置為AsyncLogger/Root添加includeThreadContexttrue。異步任務(wù)中l(wèi)ogId丟失1. 未使用TaskDecorator或CloseableThreadContext傳遞上下文。2. 自定義線程池未處理上下文傳遞。1. 為Async使用的線程池配置TaskDecorator。2. 對于手動創(chuàng)建的線程或線程池使用CloseableThreadContext包裝Runnable任務(wù)。微服務(wù)調(diào)用鏈logId中斷1. HTTP/RPC客戶端未添加攔截器來傳遞請求頭。2. 服務(wù)端未從請求頭中讀取并設(shè)置到MDC。3. 網(wǎng)關(guān)未生成或轉(zhuǎn)發(fā)X-Request-ID。1. 檢查RestTemplate/Feign/Dubbo的攔截器配置是否正確加載。2. 確保服務(wù)端的Filter/Interceptor能正確讀取約定的請求頭如X-Request-ID。3. 在網(wǎng)關(guān)層如Spring Cloud Gateway, Nginx統(tǒng)一生成和轉(zhuǎn)發(fā)請求ID。定時(shí)任務(wù)等非請求場景無logId定時(shí)任務(wù)、命令行程序等沒有HTTP請求入口因此Filter/Interceptor不會執(zhí)行。1. 在定時(shí)任務(wù)的run方法開始時(shí)手動生成并設(shè)置一個(gè)logId到MDC。2. 使用try...finally確保任務(wù)結(jié)束后清理MDC。logId在異常堆棧中不顯示異常打印時(shí)默認(rèn)的e.printStackTrace()或日志框架的異常輸出不包含MDC信息。確保使用日志框架如logger.error(錯(cuò)誤信息, e)來記錄異常這樣異常信息會和帶有l(wèi)ogId的日志行關(guān)聯(lián)。PatternLayout中的%xEx或%throwable轉(zhuǎn)換符可以輸出異常。高并發(fā)下logId串號1. 線程池復(fù)用線程MDC未清理干凈。2. 在finally塊中清理MDC的代碼未執(zhí)行如線程被強(qiáng)制中斷。1.絕對保證在請求處理結(jié)束的finally塊中調(diào)用MDC.clear()或MDC.remove(logId)。2. 審查代碼避免在finally塊之前有System.exit()或無限循環(huán)導(dǎo)致無法清理。7.2 實(shí)戰(zhàn)技巧與心得為logId添加前綴以區(qū)分來源在復(fù)雜的系統(tǒng)中日志可能來自網(wǎng)關(guān)、不同服務(wù)、定時(shí)任務(wù)?？梢栽趌ogId前加一個(gè)簡短前綴如GW-網(wǎng)關(guān)、US-用戶服務(wù)、JOB-定時(shí)任務(wù)這樣在日志聚合平臺如ELK中一眼就能看出日志來源。將logId返回給前端對于API請求可以將logId放在HTTP響應(yīng)頭如X-Request-ID或JSON響應(yīng)體的一個(gè)字段中。當(dāng)用戶報(bào)告錯(cuò)誤時(shí)讓他們提供這個(gè)ID能極大提升排查效率。前端在遇到錯(cuò)誤時(shí)也可以自動在錯(cuò)誤彈窗中展示這個(gè)ID。在日志聚合平臺中利用logId如果你使用ELKElasticsearch, Logstash, Kibana或Graylog可以將logId作為一個(gè)獨(dú)立的字段進(jìn)行索引。這樣在Kibana中你可以直接搜索某個(gè)特定的logId瞬間看到這次請求在所有微服務(wù)中產(chǎn)生的所有日志實(shí)現(xiàn)真正的分布式追蹤。小心MDC的內(nèi)存泄漏這是老生常談但至關(guān)重要的一點(diǎn)。ThreadLocalMDC的基石在線程池場景下是內(nèi)存泄漏的重災(zāi)區(qū)。務(wù)必、務(wù)必、務(wù)必在try...finally的finally塊中清理。一個(gè)檢查方法是監(jiān)控你的應(yīng)用線程數(shù)如果線程數(shù)穩(wěn)定但內(nèi)存持續(xù)增長就要懷疑MDC清理的問題。考慮使用更專業(yè)的分布式追蹤系統(tǒng)對于大型微服務(wù)系統(tǒng)手動管理logId透傳會變得繁瑣且容易出錯(cuò)。此時(shí)應(yīng)考慮引入專業(yè)的APM應(yīng)用性能管理工具如SkyWalking、Zipkin或Jaeger。它們通過字節(jié)碼增強(qiáng)或探針的方式自動完成鏈路追蹤、上下文傳遞和性能監(jiān)控功能遠(yuǎn)比一個(gè)簡單的logId強(qiáng)大。你的logId可以作為這些系統(tǒng)的TraceId的一部分實(shí)現(xiàn)平滑過渡。配置Log4j2的logId看似是一個(gè)簡單的日志格式調(diào)整實(shí)則是構(gòu)建可觀測性系統(tǒng)的基石。它強(qiáng)迫我們以“請求鏈路”的視角來思考日志記錄而不是孤立地看待每一條日志信息。從Filter中那幾行簡單的MDC.put()和MDC.remove()開始到處理異步、跨服務(wù)調(diào)用這些復(fù)雜場景每一步都是在為快速定位線上問題、理解系統(tǒng)行為鋪平道路。當(dāng)你第一次通過一個(gè)logId在幾秒鐘內(nèi)從數(shù)千萬條日志中精準(zhǔn)拉出某個(gè)用戶失敗請求的完整軌跡時(shí)你就會覺得這一切的配置和踩坑都是值得的。