日志體系設(shè)計(jì)：從規(guī)范化、鏈路追蹤到采集告警的完整實(shí)踐)
微服務(wù)架構(gòu)上線之后業(yè)務(wù)需求迭代越來越快但有一個(gè)問題始終繞不開線上出故障了怎么快速定位在單體時(shí)代系統(tǒng)只有一個(gè)進(jìn)程日志基本都寫在同一個(gè)文件里排障的路徑很直接——登錄服務(wù)器、翻日志、找異常、修復(fù)、重啟。但微服務(wù)化之后一次用戶請(qǐng)求往往要經(jīng)過網(wǎng)關(guān)、鑒權(quán)服務(wù)、業(yè)務(wù)服務(wù)、消息隊(duì)列、緩存、數(shù)據(jù)庫等多個(gè)節(jié)點(diǎn)每個(gè)節(jié)點(diǎn)都有自己的日志文件。如果日志體系沒設(shè)計(jì)好排障就變成了“登錄十臺(tái)服務(wù)器翻幾十個(gè)日志文件靠肉眼拼湊調(diào)用鏈”的原始狀態(tài)。我見過不少團(tuán)隊(duì)微服務(wù)拆分做得不錯(cuò)但日志體系還停留在“每個(gè)服務(wù)各自打印日志、各自落盤”的階段。一旦出現(xiàn)P0級(jí)故障需要跨服務(wù)排查時(shí)效率極低。這篇文章會(huì)從生產(chǎn)環(huán)境的角度完整拆解一套微服務(wù)日志體系的設(shè)計(jì)思路日志規(guī)范、采集傳輸、鏈路追蹤、存儲(chǔ)檢索、告警排查并給出可落地的 Spring Cloud 示例。無論你是剛開始搭建微服務(wù)框架還是正在優(yōu)化現(xiàn)有日志方案這篇都能提供參考。1. 微服務(wù)日志體系到底在解決什么問題先給微服務(wù)日志體系下個(gè)定義它不是一個(gè)日志框架也不是某個(gè)中間件而是一整套從日志產(chǎn)生、采集、傳輸、存儲(chǔ)、檢索到監(jiān)控告警的閉環(huán)方案。1.1 微服務(wù)排障的三個(gè)核心痛點(diǎn)微服務(wù)拆分之后日志排障最痛的三個(gè)問題可以總結(jié)為日志太散、請(qǐng)求無痕、排障太慢。日志太散指的是日志不再集中在單機(jī)文件里而是分散在各服務(wù)節(jié)點(diǎn)。業(yè)務(wù)服務(wù)可能部署了多實(shí)例下游還有緩存、MQ、數(shù)據(jù)庫的日志出了問題不知道該先看哪個(gè)服務(wù)。請(qǐng)求無痕指的是無法把一次完整的用戶請(qǐng)求串聯(lián)起來。用戶在訂單服務(wù)創(chuàng)建了訂單支付服務(wù)扣了款庫存服務(wù)減了庫存這些操作散落在不同日志文件里缺少一個(gè)統(tǒng)一的標(biāo)識(shí)把它們關(guān)聯(lián)起來。沒有統(tǒng)一 TraceId 的日志本質(zhì)上是一堆孤立的數(shù)據(jù)。排障太慢則是前兩個(gè)問題導(dǎo)致的最終結(jié)果。日志分散、無關(guān)聯(lián)排查一個(gè)跨服務(wù)問題可能要從網(wǎng)關(guān)日志開始一層層人工串聯(lián)運(yùn)氣好幾分鐘運(yùn)氣不好幾個(gè)小時(shí)。1.2 生產(chǎn)級(jí)日志體系的四個(gè)能力維度生產(chǎn)級(jí)不是口號(hào)一套能應(yīng)對(duì)線上故障的日志體系至少要具備四個(gè)能力能力維度具體要求解決什么問題日志規(guī)范統(tǒng)一格式、統(tǒng)一字段、統(tǒng)一級(jí)別讓日志可解析、可檢索鏈路追蹤TraceId 貫穿全鏈路讓一次請(qǐng)求可串聯(lián)采集傳輸高吞吐、低延遲、不丟失讓日志能及時(shí)匯聚到統(tǒng)一平臺(tái)存儲(chǔ)檢索冷熱分層、快速檢索讓海量日志能查得快、存得起這四個(gè)維度缺一不可。很多團(tuán)隊(duì)只做了第一個(gè)維度統(tǒng)一了日志格式但采集鏈路和鏈路追蹤沒跟上線上故障時(shí)還是要靠人工登服務(wù)器排查。1.3 開發(fā)人員需要掌握到什么程度作為后端開發(fā)不需要每個(gè)人都是 ELK 專家但至少要懂三件事第一如何在自己的服務(wù)里輸出符合規(guī)范的日志包括統(tǒng)一格式和級(jí)別控制。第二如何讓日志帶上 TraceId并且能跨服務(wù)傳遞。第三如何在日志采集鏈路出問題時(shí)配合運(yùn)維定位是日志框架配置問題、采集端問題還是存儲(chǔ)檢索問題。把這三件事做好絕大多數(shù)排障場(chǎng)景都能覆蓋。2. 日志規(guī)范先統(tǒng)一格式再談工具鏈日志體系的第一步不是上 ELK而是定義日志規(guī)范。沒有統(tǒng)一規(guī)范的日志采集上來也沒有意義——格式亂七八糟無法解析成結(jié)構(gòu)化字段檢索就只能靠全文搜索關(guān)鍵詞效率極低。2.1 日志格式設(shè)計(jì)原則生產(chǎn)環(huán)境推薦使用 JSON 格式輸出日志。相比純文本日志JSON 日志最大的好處是天然可解析采集端拿到一條日志就可以直接映射成結(jié)構(gòu)化字段后續(xù)在 Kibana 里可以按照字段篩選、聚合、統(tǒng)計(jì)。一個(gè)標(biāo)準(zhǔn)的微服務(wù)日志 JSON 結(jié)構(gòu)至少要包含這些字段{ timestamp: 2025-06-15 20:31:08.123, level: ERROR, traceId: 4a3f8c90d2e1b7a5, service: order-service, instance: 192.168.1.112, thread: http-nio-8080-exec-3, logger: com.example.order.service.OrderServiceImpl, message: 訂單創(chuàng)建失敗, exception: java.lang.NullPointerException: xxx, durationMs: 152, userId: U10086 }每個(gè)字段的含義和作用字段含義作用timestamp日志產(chǎn)生時(shí)間排障時(shí)按時(shí)間線分析level日志級(jí)別快速過濾 ERROR/WARNtraceId鏈路追蹤 ID串聯(lián)一次完整請(qǐng)求service服務(wù)名稱定位是哪個(gè)服務(wù)instance實(shí)例 IP定位是哪個(gè)實(shí)例thread線程名排查并發(fā)問題logger代碼位置定位到類和方法message業(yè)務(wù)描述日志主體內(nèi)容exception異常堆棧排查根因durationMs耗時(shí)分析性能瓶頸userId業(yè)務(wù)字段按用戶維度檢索2.2 日志級(jí)別到底怎么定日志級(jí)別是排障的基礎(chǔ)如果級(jí)別使用混亂日志量要么爆炸要么缺失。生產(chǎn)環(huán)境建議這樣約定級(jí)別適用場(chǎng)景示例DEBUG開發(fā)調(diào)試生產(chǎn)關(guān)閉SQL 參數(shù)、方法入?yún)⒊鰠NFO關(guān)鍵業(yè)務(wù)節(jié)點(diǎn)請(qǐng)求開始、訂單創(chuàng)建成功、支付回調(diào)WARN有潛在風(fēng)險(xiǎn)但能繼續(xù)運(yùn)行重試下次、緩存穿透、降級(jí)觸發(fā)ERROR業(yè)務(wù)異常或系統(tǒng)異常調(diào)用下游失敗、數(shù)據(jù)校驗(yàn)異常、未捕獲異常一個(gè)值得注意的點(diǎn)ERROR 級(jí)別不能濫用。有些團(tuán)隊(duì)把業(yè)務(wù)上的可預(yù)期異常比如參數(shù)校驗(yàn)失敗也打印成 ERROR結(jié)果就是日志平臺(tái)里 ERROR 刷屏真正需要關(guān)注的系統(tǒng)級(jí)異常反而被淹沒了。ERROR 應(yīng)該留給程序員真正需要處理的問題而不是所有異常都往 ERROR 里扔。2.3 日志框架選型Logback SLF4JJava 生態(tài)下日志門面用 SLF4J實(shí)現(xiàn)推薦 Logback。Spring Boot 默認(rèn)就是這套組合不需要額外引入。核心配置如下configuration !-- 日志輸出格式 -- property namePATTERN value%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%X{traceId}] [%thread] [%logger{40}] - %msg%n/ !-- 控制臺(tái)輸出 -- appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder classch.qos.logback.classic.encoder.PatternLayoutEncoder pattern${PATTERN}/pattern charsetUTF-8/charset /encoder /appender !-- 文件輸出 -- appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender file/var/log/order-service/order-service.log/file rollingPolicy classch.qos.logback.core.rolling.TimeBasedRollingPolicy fileNamePattern/var/log/order-service/order-service.%d{yyyy-MM-dd}.%i.log/fileNamePattern maxHistory15/maxHistory timeBasedFileNamingAndTriggeringPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedFNATP maxFileSize500MB/maxFileSize /timeBasedFileNamingAndTriggeringPolicy /rollingPolicy encoder classch.qos.logback.classic.encoder.PatternLayoutEncoder pattern${PATTERN}/pattern charsetUTF-8/charset /encoder /appender root levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ /root /configuration這個(gè)配置里有幾個(gè)生產(chǎn)環(huán)境必須注意的點(diǎn)日志按天滾動(dòng)同時(shí)限制單文件最大 500MB防止磁盤被撐爆。保留 15 天的歷史日志如果審計(jì)或合規(guī)有更長(zhǎng)要求再加冷存儲(chǔ)方案。%X{traceId}是 MDCMapped Diagnostic Context中的 key鏈路追蹤的核心就在這里——把 TraceId 放進(jìn) MDCLogback 會(huì)自動(dòng)把它打在每行日志上下一篇會(huì)詳細(xì)介紹。3. 鏈路追蹤TraceId 如何貫穿每一次請(qǐng)求日志規(guī)范解決了格式問題但要讓一次跨服務(wù)請(qǐng)求的日志串聯(lián)起來必須引入 TraceId 機(jī)制。3.1 MDC 是什么MDC 是 SLF4J 提供的一個(gè)功能可以把它理解成一個(gè)線程級(jí)別的 Map。在代碼里往 MDC 里放入 key-value之后在這個(gè)線程中打印的所有日志都可以在 layout 中通過%X{key}引用這個(gè)值。這就解決了“日志怎么帶上請(qǐng)求唯一標(biāo)識(shí)”的問題。在請(qǐng)求入口生成 TraceId放入 MDC整個(gè)請(qǐng)求鏈路中所有日志都會(huì)帶上這個(gè) ID。3.2 如何實(shí)現(xiàn) TraceId 跨服務(wù)傳遞在 HTTP 網(wǎng)關(guān)層面攔截所有請(qǐng)求如果是新的請(qǐng)求生成 TraceId如果是內(nèi)部服務(wù)調(diào)用從上游傳遞的 Header 中取 TraceId。然后把 TraceId 放入 MDC。Spring Cloud 項(xiàng)目推薦用 Filter 實(shí)現(xiàn)這個(gè)邏輯因?yàn)?Filter 在 Spring MVC 的處理鏈路最外層可以覆蓋所有 Controller 方法。// 文件路徑src/main/java/com/example/common/trace/TraceIdFilter.java Component Order(1) public class TraceIdFilter implements Filter { private static final String TRACE_ID_HEADER X-Trace-Id; private static final String TRACE_ID_MDC_KEY traceId; Override public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException { HttpServletRequest request (HttpServletRequest) servletRequest; String traceId request.getHeader(TRACE_ID_HEADER); if (StringUtils.isBlank(traceId)) { traceId UUID.randomUUID().toString().replace(-, ); } MDC.put(TRACE_ID_MDC_KEY, traceId); try { filterChain.doFilter(servletRequest, servletResponse); } finally { MDC.remove(TRACE_ID_MDC_KEY); } } }注意兩個(gè)細(xì)節(jié)第一個(gè)finally中必須清除 MDC 中的 traceId否則線程池復(fù)用時(shí)下一個(gè)請(qǐng)求會(huì)帶上上一個(gè)請(qǐng)求的 TraceId導(dǎo)致日志串號(hào)。第二個(gè)這里用了MDC.remove而不是MDC.clear避免誤刪其他服務(wù)設(shè)置的上下文信息。3.3 服務(wù)間調(diào)用如何傳遞 TraceId網(wǎng)關(guān)生成了 TraceId 后服務(wù)之間調(diào)用時(shí)需要把 TraceId 放在 HTTP Header 中傳給下一個(gè)服務(wù)。在 Spring Cloud 項(xiàng)目中可以用 RestTemplate 的攔截器實(shí)現(xiàn)// 文件路徑src/main/java/com/example/common/trace/TraceIdRestTemplateInterceptor.java public class TraceIdRestTemplateInterceptor implements ClientHttpRequestInterceptor { private static final String TRACE_ID_HEADER X-Trace-Id; private static final String TRACE_ID_MDC_KEY traceId; Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { String traceId MDC.get(TRACE_ID_MDC_KEY); if (StringUtils.isNotBlank(traceId)) { request.getHeaders().add(TRACE_ID_HEADER, traceId); } return execution.execute(request, body); } }Feign 項(xiàng)目也類似實(shí)現(xiàn)RequestInterceptor接口在請(qǐng)求發(fā)出前把 TraceId 寫入 Header。// 文件路徑src/main/java/com/example/common/trace/TraceIdFeignInterceptor.java Component public class TraceIdFeignInterceptor implements RequestInterceptor { private static final String TRACE_ID_HEADER X-Trace-Id; private static final String TRACE_ID_MDC_KEY traceId; Override public void apply(RequestTemplate template) { String traceId MDC.get(TRACE_ID_MDC_KEY); if (StringUtils.isNotBlank(traceId)) { template.header(TRACE_ID_HEADER, traceId); } } }這樣配置之后從外部請(qǐng)求進(jìn)入網(wǎng)關(guān)到服務(wù) A 調(diào)用服務(wù) B再到服務(wù) B 落庫整個(gè)鏈條上的日志都會(huì)帶同一個(gè) TraceId。后續(xù)在日志平臺(tái)里只需要拿這個(gè) TraceId 一搜就拿到了完整調(diào)用鏈上的所有日志。3.4 異步線程池場(chǎng)景怎么處理如果業(yè)務(wù)代碼里用了Async、線程池、MQ 消費(fèi)者會(huì)自動(dòng)丟失 MDC 上下文。比如線程池里拋了異常日志打到文件和日志平臺(tái)但 traceId 是空的排障就又回到起點(diǎn)。處理辦法是封裝一個(gè)線程池裝飾器提交任務(wù)時(shí)把當(dāng)前線程的 MDC 內(nèi)容傳入新線程// 文件路徑src/main/java/com/example/common/trace/MDCRunnable.java public class MDCRunnable implements Runnable { private final Runnable runnable; private final MapString, String mdcContext; public MDCRunnable(Runnable runnable) { this.runnable runnable; this.mdcContext MDC.getCopyOfContextMap(); } Override public void run() { if (mdcContext null) { MDC.clear(); } else { MDC.setContextMap(mdcContext); } try { runnable.run(); } finally { MDC.clear(); } } }然后在創(chuàng)建線程池的地方統(tǒng)一使用new ThreadPoolExecutor(..., new MDCRunnable(...))包裝任務(wù)。這個(gè)細(xì)節(jié)很多團(tuán)隊(duì)會(huì)忽略但線上排查時(shí)異步日志丟 TraceId 的情況非常常見。4. 日志采集與傳輸從服務(wù)日志到統(tǒng)一平臺(tái)的管道日志規(guī)范化和 TraceId 解決了日志內(nèi)容的問題接下來要做的是把分布式節(jié)點(diǎn)上的日志統(tǒng)一采集到日志平臺(tái)。這一步的架構(gòu)設(shè)計(jì)直接影響日志的實(shí)時(shí)性和可靠性。4.1 主流采集方案對(duì)比生產(chǎn)環(huán)境中常見的日志采集方案有三種方案組件優(yōu)點(diǎn)缺點(diǎn)方案一Filebeat Elasticsearch輕量、部署簡(jiǎn)單高峰時(shí) ES 寫入壓力大無緩沖方案二Filebeat Kafka Logstash ES削峰填谷、可靠性高組件多運(yùn)維復(fù)雜方案三Fluentd Kafka ES插件豐富、Ruby 生態(tài)性能略遜 Filebeat對(duì)于生產(chǎn)級(jí)微服務(wù)架構(gòu)最推薦方案二Filebeat 負(fù)責(zé)采集文件Kafka 作為消息緩沖Logstash 做數(shù)據(jù)清洗和轉(zhuǎn)換Es 負(fù)責(zé)存儲(chǔ)Kibana 負(fù)責(zé)可視化。這套架構(gòu)的核心優(yōu)勢(shì)是引入了 Kafka 緩沖層。業(yè)務(wù)高峰期日志產(chǎn)生速率可能瞬間暴漲如果直接打到 ES很容易導(dǎo)致寫入瓶頸。Kafka 可以把削峰填谷的作用Logstash 從 Kafka 消費(fèi)日志的速率相對(duì)可控ES 的寫入壓力會(huì)平穩(wěn)很多。4.2 Filebeat 采集配置每臺(tái)服務(wù)器上部署 Filebeat監(jiān)聽到本機(jī)微服務(wù)日志文件的追加內(nèi)容然后把日志發(fā)送到 Kafka。# 文件路徑/etc/filebeat/filebeat.yml filebeat.inputs: - type: log enabled: true paths: - /var/log/order-service/*.log fields: service: order-service env: prod fields_under_root: true json.keys_under_root: true json.overwrite_keys: true output.kafka: hosts: [kafka1:9092, kafka2:9092] topic: micro-service-log partition.round_robin: reachable_only: true version: 2.0.0這個(gè)配置做了三件事讀取指定路徑的日志文件給日志添加service: order-service和env: prod兩個(gè)標(biāo)簽用于標(biāo)識(shí)日志來源把 JSON 日志的 key 提升到根字段方便后續(xù)在 ES 中檢索。4.3 Kafka Topic 設(shè)計(jì)Topic 是日志匯聚的中轉(zhuǎn)站。Topic 數(shù)量不建議按服務(wù)拆太細(xì)否則運(yùn)維成本高。推薦設(shè)計(jì)如下場(chǎng)景Topic 設(shè)計(jì)說明全量日志micro-service-log所有服務(wù)的基礎(chǔ)日志慢查詢?nèi)罩緎low-sql-log數(shù)據(jù)庫中耗時(shí)較高的 SQL訪問日志access-log網(wǎng)關(guān)和服務(wù)的 HTTP 訪問日志告警日志alert-log需要觸達(dá)開發(fā)人員的異常日志區(qū)分不同的 Topic可以讓 Logstash 按不同策略處理比如訪問日志需要統(tǒng)計(jì) P99 耗時(shí)慢 SQL 日志需要單獨(dú)告警。4.4 Logstash 配置示例Logstash 的職責(zé)是從 Kafka 消費(fèi)日志做必要的字段解析、清洗再寫入 ES。# 文件路徑/etc/logstash/conf.d/logstash.conf input { kafka { bootstrap_servers kafka1:9092,kafka2:9092 topics_pattern micro-service-.* codec json consumer_threads 4 } } filter { # 如果日志中沒有 timestamp使用日志中的 timestamp 字段 if [timestamp] { date { match [timestamp, yyyy-MM-dd HH:mm:ss.SSS] target timestamp } } # 解析耗時(shí)字段為整型方便后續(xù)聚合分析 if [durationMs] { mutate { convert { durationMs integer } } } } output { elasticsearch { hosts [es1:9200, es2:9200, es3:9200] index micro-service-log-%{YYYY.MM.dd} } }注意codec json很重要因?yàn)榍懊娑x了日志是 JSON 格式Logstash 會(huì)直接解析成 JSON 字段后面的 filter 才能對(duì)字段進(jìn)行操作。5. 業(yè)務(wù)日志埋點(diǎn)最佳實(shí)踐工具鏈搭好了如果不注意業(yè)務(wù)日志的埋點(diǎn)規(guī)范日志平臺(tái)還是查不出問題。這里分享幾個(gè)生產(chǎn)環(huán)境最常用的埋點(diǎn)實(shí)踐。5.1 什么是有效的業(yè)務(wù)日志好的業(yè)務(wù)日志要能回答三個(gè)問題當(dāng)時(shí)在做什么、數(shù)據(jù)是什么樣的、結(jié)果是什么。差的日志只有一句 “操作失敗”沒有任何上下文信息排障時(shí)等于沒有日志。5.2 核心業(yè)務(wù)埋點(diǎn)示例訂單服務(wù)創(chuàng)建訂單這個(gè)核心節(jié)點(diǎn)推薦這樣埋點(diǎn)// 文件路徑src/main/java/com/example/order/service/OrderServiceImpl.java Slf4j Service public class OrderServiceImpl implements OrderService { Override public OrderCreateResult createOrder(OrderCreateRequest request) { Long orderId null; long startTime System.currentTimeMillis(); try { log.info([createOrder] 開始創(chuàng)建訂單, userId{}, skuId{}, quantity{}, request.getUserId(), request.getSkuId(), request.getQuantity()); // 業(yè)務(wù)邏輯 orderId doCreateOrder(request); log.info([createOrder] 訂單創(chuàng)建成功, orderId{}, costMs{}, orderId, System.currentTimeMillis() - startTime); return OrderCreateResult.success(orderId); } catch (Exception e) { log.error([createOrder] 訂單創(chuàng)建失敗, userId{}, skuId{}, quantity{}, request.getUserId(), request.getSkuId(), request.getQuantity(), e); throw e; } finally { log.info([createOrder] 訂單創(chuàng)建結(jié)束, orderId{}, costMs{}, orderId, System.currentTimeMillis() - startTime); } } }這個(gè)埋點(diǎn)的好處是日志中能看到入?yún)?、結(jié)果、耗時(shí)失敗時(shí)有異常堆棧同時(shí)保留了上下文參數(shù)costMs可以用于后續(xù)性能分析發(fā)現(xiàn)訂單創(chuàng)建越來越慢時(shí)直接查日志平臺(tái)里createOrder的耗時(shí)趨勢(shì)。5.3 遠(yuǎn)程調(diào)用日志微服務(wù)排障最常遇到的問題是用戶說下單失敗到底是訂單服務(wù)的問題還是庫存服務(wù)的問題還是下游 HTTP 接口的問題。遠(yuǎn)程調(diào)用必須記錄日志而且要記錄全量鏈路信息。// 文件路徑src/main/java/com/example/common/log/RpcLogAspect.java Aspect Component Slf4j public class RpcLogAspect { Around(annotation(com.example.common.log.RpcLog)) public Object around(ProceedingJoinPoint joinPoint) throws Throwable { MethodSignature signature (MethodSignature) joinPoint.getSignature(); Method method signature.getMethod(); RpcLog rpcLog method.getAnnotation(RpcLog.class); String targetService rpcLog.service(); String methodName method.getName(); long start System.currentTimeMillis(); Object result null; try { result joinPoint.proceed(); return result; } catch (Exception e) { log.error([RPC] {}#{} 調(diào)用異常, costMs{}, targetService, methodName, System.currentTimeMillis() - start, e); throw e; } finally { log.info([RPC] {}#{} 調(diào)用完成, result{}, costMs{}, targetService, methodName, JSON.toJSONString(result), System.currentTimeMillis() - start); } } }這里可以給遠(yuǎn)程調(diào)用方法定義注解RpcLog(service inventory-service)切面自動(dòng)記錄遠(yuǎn)程調(diào)用日志。之后排查跨服務(wù)問題時(shí)通過 TraceId 搜日志能直接看到庫存服務(wù)調(diào)用返回了什么結(jié)果耗時(shí)多少。5.4 避免日志打爆磁盤的三個(gè)建議日志不是打得越多越好。生產(chǎn)環(huán)境幾個(gè)典型問題業(yè)務(wù)代碼每行都打日志、循環(huán)體里打日志、打印大對(duì)象導(dǎo)致的日志量爆炸。三個(gè)建議第一不要在 for 循環(huán)中打 INFO 日志。如果循環(huán)一萬次日志會(huì)膨脹一萬倍?？梢栽谘h(huán)結(jié)束后匯總打印一次。第二不要打印整個(gè)大對(duì)象的 toString。比如一個(gè)包含用戶敏感信息的對(duì)象JSON 序列化后可能有幾 KB多打幾次就可能把磁盤或 Kafka 帶寬打爆。第三日志內(nèi)容遵守脫敏要求。密碼、手機(jī)號(hào)、身份證、銀行卡號(hào)等敏感字段打印前必須先脫敏。6. 日志存儲(chǔ)、檢索與可視化日志經(jīng)過采集傳輸后最終落到 ES 中。這一層的設(shè)計(jì)直接決定日志查詢體驗(yàn)。6.1 Elasticsearch 索引策略日志類數(shù)據(jù)的索引策略核心是時(shí)間分區(qū)。根據(jù)日志量選擇按天或按月創(chuàng)建索引。日志量規(guī)模索引策略說明日均 10GB按天分索引數(shù)據(jù)量小查詢效率高日均 10GB-100GB按天分索引 冷熱分離配合 ILM 生命周期管理日均 100GB按小時(shí)分索引控制單個(gè)索引的 shard 規(guī)模推薦使用索引生命周期管理ILM策略自動(dòng)完成熱索引到冷索引的切換以及舊數(shù)據(jù)的清理。6.2 Kibana 檢索技巧日志平臺(tái)搭好后開發(fā)最常用的場(chǎng)景就是按 TraceId 檢索。Kibana Discover 頁面可以這樣查{ query: { bool: { must: [ { term: { traceId.keyword: 4a3f8c90d2e1b7a5 } } ] } } }如果你的日志里 traceId 保存為keyword類型可以用term精確匹配。如果日志是text類型則需要用match。建議在 ES mapping 中把 traceId 設(shè)置為keyword以便精確查詢。6.3 慢查詢與錯(cuò)誤日志單獨(dú)視圖如果所有日志都混在一個(gè)索引里排障時(shí)過濾條件很麻煩。建議在 Kibana 中建立兩個(gè)常用視圖鏈路追蹤視圖按 traceId 反查完整調(diào)用鏈快速判斷故障發(fā)生在哪個(gè)環(huán)節(jié)。錯(cuò)誤告警視圖按 level: ERROR 過濾配合 service、instance 字段在一個(gè)頁面看到所有服務(wù)當(dāng)前的報(bào)錯(cuò)情況。7. 基于日志的監(jiān)控告警日志體系不只是用來事后查日志的更重要的價(jià)值在于及時(shí)發(fā)現(xiàn)潛在故障。7.1 哪些日志需要告警生產(chǎn)環(huán)境的告警要克制只告警需要人處理的問題。推薦設(shè)置四類日志告警告警規(guī)則觸發(fā)條件處理對(duì)象異常堆積告警單服務(wù) ERROR 日志 5 分鐘超過 50 條開發(fā)值班熔斷降級(jí)觸發(fā)告警WARN 日志中出現(xiàn)降級(jí)關(guān)鍵詞開發(fā)值班超時(shí)告警遠(yuǎn)程調(diào)用耗時(shí)超過 2 秒的日志開發(fā) 運(yùn)維日志量異常告警某服務(wù)日志量突增 5 倍排查日志刷屏7.2 基于 ElastAlert 的告警示例ElastAlert 是配合 ES 使用的告警組件。一個(gè)簡(jiǎn)單的高頻錯(cuò)誤告警配置如下# 文件路徑/etc/elastalert/rules/error_rate.yaml name: high-error-rate type: frequency index: micro-service-log-* num_events: 50 timeframe: minutes: 5 filter: - term: level.keyword: ERROR alert: - dingtalk dingtalk_webhook_url: https://oapi.dingtalk.com/robot/send?access_tokenxxx alert_text: 告警微服務(wù)ERROR日志5分鐘超過50條當(dāng) 5 分鐘內(nèi) ERROR 日志超過 50 條時(shí)ElastAlert 推送告警到釘釘或企業(yè)微信。告警的目的是讓故障發(fā)現(xiàn)時(shí)間從用戶反饋?zhàn)兂上到y(tǒng)自動(dòng)告警這是生產(chǎn)級(jí)體系的一個(gè)重要能力。7.3 告警治理告警疲勞問題告警太多容易造成告警疲勞真正的故障反而被淹沒?？梢宰鋈朗諗恳皇欠旨?jí)。P0 告警業(yè)務(wù)不可用、主鏈路異常通知到人P2 告警性能下降、慢查詢只記錄到周報(bào)。二是聚合。同一服務(wù)同一類錯(cuò)誤在 10 分鐘內(nèi)只觸發(fā)一次避免凌晨被幾十條相同告警轟炸。三是去重。告警時(shí)帶上 TraceId 和異常摘要開發(fā)可以直接在日志平臺(tái)定位問題。8. 常見日志排障問題與排查思路日志體系運(yùn)行一段時(shí)間后會(huì)遇到各種問題。以下是我在實(shí)際項(xiàng)目中遇到的幾個(gè)高頻問題。問題現(xiàn)象常見原因解決思路Kibana 搜不到今天的日志Filebeat 未重啟或日志文件路徑不對(duì)檢查 Filebeat 狀態(tài)測(cè)試采集連通性日志里有大量空 traceIdFilter 沒生效或異步線程丟了 MDC檢查 Filter 注冊(cè)順序檢查異步線程池包裝ES 寫入慢導(dǎo)致消息積壓日志量超過 ES 寫入極限增加 ES 節(jié)點(diǎn)或調(diào) Kafka 消費(fèi)并發(fā)日志平臺(tái)查到但格式是純文本應(yīng)用日志輸出格式?jīng)]改成 JSON修改日志配置確認(rèn)輸出為 JSON服務(wù)重啟后老日志丟失日志路徑配置在臨時(shí)目錄把日志目錄掛載到持久化磁盤ERROR 刷屏看不出重點(diǎn)日志級(jí)別用得太泛收窄 ERROR 使用范圍配合過濾視圖8.1 TraceId 丟失問題深入排查TraceId 丟失是日志體系中最常見的問題。排查順序是先看應(yīng)用日志確認(rèn)是完全沒有 TraceId還是部分場(chǎng)景缺失。如果是部分缺失先查是否有Async異步方法或底層線程池。再看過濾器注冊(cè)順序在 Spring Boot 中自定義 Filter 要用Order聲明如果業(yè)務(wù) Filter 在 TraceIdFilter 之前執(zhí)行中間打印日志就沒有 TraceId。最后看服務(wù)間調(diào)用調(diào)用下游時(shí)是否通過 Feign 或 RestTemplate 的攔截器傳遞了 Header。下游服務(wù)如何從頭里取 TraceId 的邏輯也要檢查。8.2 日志量大導(dǎo)致存儲(chǔ)成本高怎么處理生產(chǎn)環(huán)境日志量是所有微服務(wù)團(tuán)隊(duì)的普遍痛點(diǎn)。推薦組合方案降低單條日志體量。去掉 DEBUG 日志縮短 message 內(nèi)容日志中不打印大對(duì)象。生命周期上做冷熱分層。熱數(shù)據(jù)保留 7 天冷數(shù)據(jù)壓縮存儲(chǔ)保留 30 天超過 30 天的日志歸檔到對(duì)象存儲(chǔ)。只保留關(guān)鍵字段的索引。ES 中為所有字段建索引很耗存儲(chǔ)建議對(duì) traceId、service、level、timestamp 這幾個(gè)常用檢索字段建索引其他字段設(shè)為enabled: false。9. 生產(chǎn)級(jí)日志體系落地最佳實(shí)踐最后一個(gè)章節(jié)結(jié)合實(shí)際項(xiàng)目經(jīng)驗(yàn)給出搭建日志體系時(shí)的工程建議。9.1 從最小可用搭建到逐步完善日志體系建設(shè)不建議一步到位。對(duì)于剛開始搭建微服務(wù)框架的團(tuán)隊(duì)分三個(gè)階段推進(jìn)更穩(wěn)妥第一階段先做日志規(guī)范化和 TraceId 鏈路。所有服務(wù)統(tǒng)一日志格式統(tǒng)一輸出 JSON加上 TraceId。這一階段不需要復(fù)雜工具鏈先在本地和測(cè)試環(huán)境驗(yàn)證。第二階段部署 ELK Kafka把日志采集到統(tǒng)一平臺(tái)。這一階段的目標(biāo)是讓所有服務(wù)日志都匯聚到一起能看到全局視角。第三階段加監(jiān)控告警、慢查詢分析、日志量治理。等日志平臺(tái)穩(wěn)定運(yùn)行后再逐步疊加告警規(guī)則和運(yùn)維能力。9.2 日志平臺(tái)排障流程標(biāo)準(zhǔn)化日志體系建好后開發(fā)側(cè)還需要一套標(biāo)準(zhǔn)排障流程。推薦遵循以下順序第一步用戶反饋問題時(shí)先拿訂單號(hào)或用戶 ID去日志平臺(tái)搜相關(guān)業(yè)務(wù)日志拿到 TraceId。第二步按 TraceId 全鏈路檢索看是哪一步出錯(cuò)的。如果調(diào)用下游超時(shí)看下游是否打印了異常。第三步結(jié)合異常堆棧和耗時(shí)數(shù)據(jù)判斷是代碼問題、中間件問題還是網(wǎng)絡(luò)問題。第四步定位到具體服務(wù)后查看該服務(wù)對(duì)應(yīng)實(shí)例的上下文日志補(bǔ)充排障信息。9.3 多環(huán)境日志隔離與權(quán)限控制線上日志涉及敏感信息權(quán)限控制不能省略。不同環(huán)境建議采用不同的索引前綴例如prod-log-、test-log-Kibana 層面用空間或索引權(quán)限隔離。開發(fā)人員默認(rèn)只能看測(cè)試環(huán)境日志生產(chǎn)環(huán)境日志按需申請(qǐng)權(quán)限。賬號(hào)權(quán)限遵循最小化原則不要給所有開發(fā)全量開放。9.4 日志體系也需要混沌演練日志體系本身也是系統(tǒng)也可能掛。生產(chǎn)環(huán)境每隔一段時(shí)間做一次日志平臺(tái)故障演練模擬 Filebeat 掛了會(huì)怎么樣、Kafka 消費(fèi)積壓會(huì)怎么樣、ES 節(jié)點(diǎn)宕機(jī)會(huì)怎么樣。提前發(fā)現(xiàn)問題而不是等 P0 事故時(shí)才第一次面對(duì)。10. 總結(jié)與下一步學(xué)習(xí)路線這套微服務(wù)日志體系的核心思路可以總結(jié)為一句話讓每一次用戶請(qǐng)求都有唯一的 TraceId讓每一行日志都能被結(jié)構(gòu)化采集讓每一個(gè)異常都能在日志平臺(tái)上被快速檢索和告警。文中相關(guān)內(nèi)容比較簡(jiǎn)單可以直接對(duì)照實(shí)踐先統(tǒng)一日志規(guī)范把 Logback 輸出改成 JSON 格式讓日志具備結(jié)構(gòu)化能力。再實(shí)現(xiàn) TraceId 過濾器和服務(wù)間傳遞保證一次請(qǐng)求全鏈路日志可串聯(lián)。然后部署 Filebeat Kafka Logstash ES Kibana讓日志從分散的服務(wù)器匯聚到統(tǒng)一平臺(tái)。最后在平臺(tái)層加檢索視圖和告警規(guī)則讓故障從“用戶發(fā)現(xiàn)”變成“系統(tǒng)發(fā)現(xiàn)”。對(duì)于正在從零搭建微服務(wù)框架的讀者日志體系建設(shè)不需要排在業(yè)務(wù)開發(fā)之后建議服務(wù)拆分一開始就同步做好日志規(guī)范。等系統(tǒng)真正上線后你會(huì)發(fā)現(xiàn)這套體系的價(jià)值遠(yuǎn)超預(yù)期——它是排障的底座也是穩(wěn)定性保障的地基。 微服務(wù)日志體系設(shè)計(jì)：從規(guī)范化、鏈路追蹤到采集告警的完整實(shí)踐
微服務(wù)架構(gòu)上線之后業(yè)務(wù)需求迭代越來越快但有一個(gè)問題始終繞不開線上出故障了怎么快速定位在單體時(shí)代系統(tǒng)只有一個(gè)進(jìn)程日志基本都寫在同一個(gè)文件里排障的路徑很直接——登錄服務(wù)器、翻日志、找異常、修復(fù)、重啟。但微服務(wù)化之后一次用戶請(qǐng)求往往要經(jīng)過網(wǎng)關(guān)、鑒權(quán)服務(wù)、業(yè)務(wù)服務(wù)、消息隊(duì)列、緩存、數(shù)據(jù)庫等多個(gè)節(jié)點(diǎn)每個(gè)節(jié)點(diǎn)都有自己的日志文件。如果日志體系沒設(shè)計(jì)好排障就變成了“登錄十臺(tái)服務(wù)器翻幾十個(gè)日志文件靠肉眼拼湊調(diào)用鏈”的原始狀態(tài)。我見過不少團(tuán)隊(duì)微服務(wù)拆分做得不錯(cuò)但日志體系還停留在“每個(gè)服務(wù)各自打印日志、各自落盤”的階段。一旦出現(xiàn)P0級(jí)故障需要跨服務(wù)排查時(shí)效率極低。這篇文章會(huì)從生產(chǎn)環(huán)境的角度完整拆解一套微服務(wù)日志體系的設(shè)計(jì)思路日志規(guī)范、采集傳輸、鏈路追蹤、存儲(chǔ)檢索、告警排查并給出可落地的 Spring Cloud 示例。無論你是剛開始搭建微服務(wù)框架還是正在優(yōu)化現(xiàn)有日志方案這篇都能提供參考。1. 微服務(wù)日志體系到底在解決什么問題先給微服務(wù)日志體系下個(gè)定義它不是一個(gè)日志框架也不是某個(gè)中間件而是一整套從日志產(chǎn)生、采集、傳輸、存儲(chǔ)、檢索到監(jiān)控告警的閉環(huán)方案。1.1 微服務(wù)排障的三個(gè)核心痛點(diǎn)微服務(wù)拆分之后日志排障最痛的三個(gè)問題可以總結(jié)為日志太散、請(qǐng)求無痕、排障太慢。日志太散指的是日志不再集中在單機(jī)文件里而是分散在各服務(wù)節(jié)點(diǎn)。業(yè)務(wù)服務(wù)可能部署了多實(shí)例下游還有緩存、MQ、數(shù)據(jù)庫的日志出了問題不知道該先看哪個(gè)服務(wù)。請(qǐng)求無痕指的是無法把一次完整的用戶請(qǐng)求串聯(lián)起來。用戶在訂單服務(wù)創(chuàng)建了訂單支付服務(wù)扣了款庫存服務(wù)減了庫存這些操作散落在不同日志文件里缺少一個(gè)統(tǒng)一的標(biāo)識(shí)把它們關(guān)聯(lián)起來。沒有統(tǒng)一 TraceId 的日志本質(zhì)上是一堆孤立的數(shù)據(jù)。排障太慢則是前兩個(gè)問題導(dǎo)致的最終結(jié)果。日志分散、無關(guān)聯(lián)排查一個(gè)跨服務(wù)問題可能要從網(wǎng)關(guān)日志開始一層層人工串聯(lián)運(yùn)氣好幾分鐘運(yùn)氣不好幾個(gè)小時(shí)。1.2 生產(chǎn)級(jí)日志體系的四個(gè)能力維度生產(chǎn)級(jí)不是口號(hào)一套能應(yīng)對(duì)線上故障的日志體系至少要具備四個(gè)能力能力維度具體要求解決什么問題日志規(guī)范統(tǒng)一格式、統(tǒng)一字段、統(tǒng)一級(jí)別讓日志可解析、可檢索鏈路追蹤TraceId 貫穿全鏈路讓一次請(qǐng)求可串聯(lián)采集傳輸高吞吐、低延遲、不丟失讓日志能及時(shí)匯聚到統(tǒng)一平臺(tái)存儲(chǔ)檢索冷熱分層、快速檢索讓海量日志能查得快、存得起這四個(gè)維度缺一不可。很多團(tuán)隊(duì)只做了第一個(gè)維度統(tǒng)一了日志格式但采集鏈路和鏈路追蹤沒跟上線上故障時(shí)還是要靠人工登服務(wù)器排查。1.3 開發(fā)人員需要掌握到什么程度作為后端開發(fā)不需要每個(gè)人都是 ELK 專家但至少要懂三件事第一如何在自己的服務(wù)里輸出符合規(guī)范的日志包括統(tǒng)一格式和級(jí)別控制。第二如何讓日志帶上 TraceId并且能跨服務(wù)傳遞。第三如何在日志采集鏈路出問題時(shí)配合運(yùn)維定位是日志框架配置問題、采集端問題還是存儲(chǔ)檢索問題。把這三件事做好絕大多數(shù)排障場(chǎng)景都能覆蓋。2. 日志規(guī)范先統(tǒng)一格式再談工具鏈日志體系的第一步不是上 ELK而是定義日志規(guī)范。沒有統(tǒng)一規(guī)范的日志采集上來也沒有意義——格式亂七八糟無法解析成結(jié)構(gòu)化字段檢索就只能靠全文搜索關(guān)鍵詞效率極低。2.1 日志格式設(shè)計(jì)原則生產(chǎn)環(huán)境推薦使用 JSON 格式輸出日志。相比純文本日志JSON 日志最大的好處是天然可解析采集端拿到一條日志就可以直接映射成結(jié)構(gòu)化字段后續(xù)在 Kibana 里可以按照字段篩選、聚合、統(tǒng)計(jì)。一個(gè)標(biāo)準(zhǔn)的微服務(wù)日志 JSON 結(jié)構(gòu)至少要包含這些字段{ timestamp: 2025-06-15 20:31:08.123, level: ERROR, traceId: 4a3f8c90d2e1b7a5, service: order-service, instance: 192.168.1.112, thread: http-nio-8080-exec-3, logger: com.example.order.service.OrderServiceImpl, message: 訂單創(chuàng)建失敗, exception: java.lang.NullPointerException: xxx, durationMs: 152, userId: U10086 }每個(gè)字段的含義和作用字段含義作用timestamp日志產(chǎn)生時(shí)間排障時(shí)按時(shí)間線分析level日志級(jí)別快速過濾 ERROR/WARNtraceId鏈路追蹤 ID串聯(lián)一次完整請(qǐng)求service服務(wù)名稱定位是哪個(gè)服務(wù)instance實(shí)例 IP定位是哪個(gè)實(shí)例thread線程名排查并發(fā)問題logger代碼位置定位到類和方法message業(yè)務(wù)描述日志主體內(nèi)容exception異常堆棧排查根因durationMs耗時(shí)分析性能瓶頸userId業(yè)務(wù)字段按用戶維度檢索2.2 日志級(jí)別到底怎么定日志級(jí)別是排障的基礎(chǔ)如果級(jí)別使用混亂日志量要么爆炸要么缺失。生產(chǎn)環(huán)境建議這樣約定級(jí)別適用場(chǎng)景示例DEBUG開發(fā)調(diào)試生產(chǎn)關(guān)閉SQL 參數(shù)、方法入?yún)⒊鰠NFO關(guān)鍵業(yè)務(wù)節(jié)點(diǎn)請(qǐng)求開始、訂單創(chuàng)建成功、支付回調(diào)WARN有潛在風(fēng)險(xiǎn)但能繼續(xù)運(yùn)行重試下次、緩存穿透、降級(jí)觸發(fā)ERROR業(yè)務(wù)異常或系統(tǒng)異常調(diào)用下游失敗、數(shù)據(jù)校驗(yàn)異常、未捕獲異常一個(gè)值得注意的點(diǎn)ERROR 級(jí)別不能濫用。有些團(tuán)隊(duì)把業(yè)務(wù)上的可預(yù)期異常比如參數(shù)校驗(yàn)失敗也打印成 ERROR結(jié)果就是日志平臺(tái)里 ERROR 刷屏真正需要關(guān)注的系統(tǒng)級(jí)異常反而被淹沒了。ERROR 應(yīng)該留給程序員真正需要處理的問題而不是所有異常都往 ERROR 里扔。2.3 日志框架選型Logback SLF4JJava 生態(tài)下日志門面用 SLF4J實(shí)現(xiàn)推薦 Logback。Spring Boot 默認(rèn)就是這套組合不需要額外引入。核心配置如下configuration !-- 日志輸出格式 -- property namePATTERN value%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%X{traceId}] [%thread] [%logger{40}] - %msg%n/ !-- 控制臺(tái)輸出 -- appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder classch.qos.logback.classic.encoder.PatternLayoutEncoder pattern${PATTERN}/pattern charsetUTF-8/charset /encoder /appender !-- 文件輸出 -- appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender file/var/log/order-service/order-service.log/file rollingPolicy classch.qos.logback.core.rolling.TimeBasedRollingPolicy fileNamePattern/var/log/order-service/order-service.%d{yyyy-MM-dd}.%i.log/fileNamePattern maxHistory15/maxHistory timeBasedFileNamingAndTriggeringPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedFNATP maxFileSize500MB/maxFileSize /timeBasedFileNamingAndTriggeringPolicy /rollingPolicy encoder classch.qos.logback.classic.encoder.PatternLayoutEncoder pattern${PATTERN}/pattern charsetUTF-8/charset /encoder /appender root levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ /root /configuration這個(gè)配置里有幾個(gè)生產(chǎn)環(huán)境必須注意的點(diǎn)日志按天滾動(dòng)同時(shí)限制單文件最大 500MB防止磁盤被撐爆。保留 15 天的歷史日志如果審計(jì)或合規(guī)有更長(zhǎng)要求再加冷存儲(chǔ)方案。%X{traceId}是 MDCMapped Diagnostic Context中的 key鏈路追蹤的核心就在這里——把 TraceId 放進(jìn) MDCLogback 會(huì)自動(dòng)把它打在每行日志上下一篇會(huì)詳細(xì)介紹。3. 鏈路追蹤TraceId 如何貫穿每一次請(qǐng)求日志規(guī)范解決了格式問題但要讓一次跨服務(wù)請(qǐng)求的日志串聯(lián)起來必須引入 TraceId 機(jī)制。3.1 MDC 是什么MDC 是 SLF4J 提供的一個(gè)功能可以把它理解成一個(gè)線程級(jí)別的 Map。在代碼里往 MDC 里放入 key-value之后在這個(gè)線程中打印的所有日志都可以在 layout 中通過%X{key}引用這個(gè)值。這就解決了“日志怎么帶上請(qǐng)求唯一標(biāo)識(shí)”的問題。在請(qǐng)求入口生成 TraceId放入 MDC整個(gè)請(qǐng)求鏈路中所有日志都會(huì)帶上這個(gè) ID。3.2 如何實(shí)現(xiàn) TraceId 跨服務(wù)傳遞在 HTTP 網(wǎng)關(guān)層面攔截所有請(qǐng)求如果是新的請(qǐng)求生成 TraceId如果是內(nèi)部服務(wù)調(diào)用從上游傳遞的 Header 中取 TraceId。然后把 TraceId 放入 MDC。Spring Cloud 項(xiàng)目推薦用 Filter 實(shí)現(xiàn)這個(gè)邏輯因?yàn)?Filter 在 Spring MVC 的處理鏈路最外層可以覆蓋所有 Controller 方法。// 文件路徑src/main/java/com/example/common/trace/TraceIdFilter.java Component Order(1) public class TraceIdFilter implements Filter { private static final String TRACE_ID_HEADER X-Trace-Id; private static final String TRACE_ID_MDC_KEY traceId; Override public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException { HttpServletRequest request (HttpServletRequest) servletRequest; String traceId request.getHeader(TRACE_ID_HEADER); if (StringUtils.isBlank(traceId)) { traceId UUID.randomUUID().toString().replace(-, ); } MDC.put(TRACE_ID_MDC_KEY, traceId); try { filterChain.doFilter(servletRequest, servletResponse); } finally { MDC.remove(TRACE_ID_MDC_KEY); } } }注意兩個(gè)細(xì)節(jié)第一個(gè)finally中必須清除 MDC 中的 traceId否則線程池復(fù)用時(shí)下一個(gè)請(qǐng)求會(huì)帶上上一個(gè)請(qǐng)求的 TraceId導(dǎo)致日志串號(hào)。第二個(gè)這里用了MDC.remove而不是MDC.clear避免誤刪其他服務(wù)設(shè)置的上下文信息。3.3 服務(wù)間調(diào)用如何傳遞 TraceId網(wǎng)關(guān)生成了 TraceId 后服務(wù)之間調(diào)用時(shí)需要把 TraceId 放在 HTTP Header 中傳給下一個(gè)服務(wù)。在 Spring Cloud 項(xiàng)目中可以用 RestTemplate 的攔截器實(shí)現(xiàn)// 文件路徑src/main/java/com/example/common/trace/TraceIdRestTemplateInterceptor.java public class TraceIdRestTemplateInterceptor implements ClientHttpRequestInterceptor { private static final String TRACE_ID_HEADER X-Trace-Id; private static final String TRACE_ID_MDC_KEY traceId; Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { String traceId MDC.get(TRACE_ID_MDC_KEY); if (StringUtils.isNotBlank(traceId)) { request.getHeaders().add(TRACE_ID_HEADER, traceId); } return execution.execute(request, body); } }Feign 項(xiàng)目也類似實(shí)現(xiàn)RequestInterceptor接口在請(qǐng)求發(fā)出前把 TraceId 寫入 Header。// 文件路徑src/main/java/com/example/common/trace/TraceIdFeignInterceptor.java Component public class TraceIdFeignInterceptor implements RequestInterceptor { private static final String TRACE_ID_HEADER X-Trace-Id; private static final String TRACE_ID_MDC_KEY traceId; Override public void apply(RequestTemplate template) { String traceId MDC.get(TRACE_ID_MDC_KEY); if (StringUtils.isNotBlank(traceId)) { template.header(TRACE_ID_HEADER, traceId); } } }這樣配置之后從外部請(qǐng)求進(jìn)入網(wǎng)關(guān)到服務(wù) A 調(diào)用服務(wù) B再到服務(wù) B 落庫整個(gè)鏈條上的日志都會(huì)帶同一個(gè) TraceId。后續(xù)在日志平臺(tái)里只需要拿這個(gè) TraceId 一搜就拿到了完整調(diào)用鏈上的所有日志。3.4 異步線程池場(chǎng)景怎么處理如果業(yè)務(wù)代碼里用了Async、線程池、MQ 消費(fèi)者會(huì)自動(dòng)丟失 MDC 上下文。比如線程池里拋了異常日志打到文件和日志平臺(tái)但 traceId 是空的排障就又回到起點(diǎn)。處理辦法是封裝一個(gè)線程池裝飾器提交任務(wù)時(shí)把當(dāng)前線程的 MDC 內(nèi)容傳入新線程// 文件路徑src/main/java/com/example/common/trace/MDCRunnable.java public class MDCRunnable implements Runnable { private final Runnable runnable; private final MapString, String mdcContext; public MDCRunnable(Runnable runnable) { this.runnable runnable; this.mdcContext MDC.getCopyOfContextMap(); } Override public void run() { if (mdcContext null) { MDC.clear(); } else { MDC.setContextMap(mdcContext); } try { runnable.run(); } finally { MDC.clear(); } } }然后在創(chuàng)建線程池的地方統(tǒng)一使用new ThreadPoolExecutor(..., new MDCRunnable(...))包裝任務(wù)。這個(gè)細(xì)節(jié)很多團(tuán)隊(duì)會(huì)忽略但線上排查時(shí)異步日志丟 TraceId 的情況非常常見。4. 日志采集與傳輸從服務(wù)日志到統(tǒng)一平臺(tái)的管道日志規(guī)范化和 TraceId 解決了日志內(nèi)容的問題接下來要做的是把分布式節(jié)點(diǎn)上的日志統(tǒng)一采集到日志平臺(tái)。這一步的架構(gòu)設(shè)計(jì)直接影響日志的實(shí)時(shí)性和可靠性。4.1 主流采集方案對(duì)比生產(chǎn)環(huán)境中常見的日志采集方案有三種方案組件優(yōu)點(diǎn)缺點(diǎn)方案一Filebeat Elasticsearch輕量、部署簡(jiǎn)單高峰時(shí) ES 寫入壓力大無緩沖方案二Filebeat Kafka Logstash ES削峰填谷、可靠性高組件多運(yùn)維復(fù)雜方案三Fluentd Kafka ES插件豐富、Ruby 生態(tài)性能略遜 Filebeat對(duì)于生產(chǎn)級(jí)微服務(wù)架構(gòu)最推薦方案二Filebeat 負(fù)責(zé)采集文件Kafka 作為消息緩沖Logstash 做數(shù)據(jù)清洗和轉(zhuǎn)換Es 負(fù)責(zé)存儲(chǔ)Kibana 負(fù)責(zé)可視化。這套架構(gòu)的核心優(yōu)勢(shì)是引入了 Kafka 緩沖層。業(yè)務(wù)高峰期日志產(chǎn)生速率可能瞬間暴漲如果直接打到 ES很容易導(dǎo)致寫入瓶頸。Kafka 可以把削峰填谷的作用Logstash 從 Kafka 消費(fèi)日志的速率相對(duì)可控ES 的寫入壓力會(huì)平穩(wěn)很多。4.2 Filebeat 采集配置每臺(tái)服務(wù)器上部署 Filebeat監(jiān)聽到本機(jī)微服務(wù)日志文件的追加內(nèi)容然后把日志發(fā)送到 Kafka。# 文件路徑/etc/filebeat/filebeat.yml filebeat.inputs: - type: log enabled: true paths: - /var/log/order-service/*.log fields: service: order-service env: prod fields_under_root: true json.keys_under_root: true json.overwrite_keys: true output.kafka: hosts: [kafka1:9092, kafka2:9092] topic: micro-service-log partition.round_robin: reachable_only: true version: 2.0.0這個(gè)配置做了三件事讀取指定路徑的日志文件給日志添加service: order-service和env: prod兩個(gè)標(biāo)簽用于標(biāo)識(shí)日志來源把 JSON 日志的 key 提升到根字段方便后續(xù)在 ES 中檢索。4.3 Kafka Topic 設(shè)計(jì)Topic 是日志匯聚的中轉(zhuǎn)站。Topic 數(shù)量不建議按服務(wù)拆太細(xì)否則運(yùn)維成本高。推薦設(shè)計(jì)如下場(chǎng)景Topic 設(shè)計(jì)說明全量日志micro-service-log所有服務(wù)的基礎(chǔ)日志慢查詢?nèi)罩緎low-sql-log數(shù)據(jù)庫中耗時(shí)較高的 SQL訪問日志access-log網(wǎng)關(guān)和服務(wù)的 HTTP 訪問日志告警日志alert-log需要觸達(dá)開發(fā)人員的異常日志區(qū)分不同的 Topic可以讓 Logstash 按不同策略處理比如訪問日志需要統(tǒng)計(jì) P99 耗時(shí)慢 SQL 日志需要單獨(dú)告警。4.4 Logstash 配置示例Logstash 的職責(zé)是從 Kafka 消費(fèi)日志做必要的字段解析、清洗再寫入 ES。# 文件路徑/etc/logstash/conf.d/logstash.conf input { kafka { bootstrap_servers kafka1:9092,kafka2:9092 topics_pattern micro-service-.* codec json consumer_threads 4 } } filter { # 如果日志中沒有 timestamp使用日志中的 timestamp 字段 if [timestamp] { date { match [timestamp, yyyy-MM-dd HH:mm:ss.SSS] target timestamp } } # 解析耗時(shí)字段為整型方便后續(xù)聚合分析 if [durationMs] { mutate { convert { durationMs integer } } } } output { elasticsearch { hosts [es1:9200, es2:9200, es3:9200] index micro-service-log-%{YYYY.MM.dd} } }注意codec json很重要因?yàn)榍懊娑x了日志是 JSON 格式Logstash 會(huì)直接解析成 JSON 字段后面的 filter 才能對(duì)字段進(jìn)行操作。5. 業(yè)務(wù)日志埋點(diǎn)最佳實(shí)踐工具鏈搭好了如果不注意業(yè)務(wù)日志的埋點(diǎn)規(guī)范日志平臺(tái)還是查不出問題。這里分享幾個(gè)生產(chǎn)環(huán)境最常用的埋點(diǎn)實(shí)踐。5.1 什么是有效的業(yè)務(wù)日志好的業(yè)務(wù)日志要能回答三個(gè)問題當(dāng)時(shí)在做什么、數(shù)據(jù)是什么樣的、結(jié)果是什么。差的日志只有一句 “操作失敗”沒有任何上下文信息排障時(shí)等于沒有日志。5.2 核心業(yè)務(wù)埋點(diǎn)示例訂單服務(wù)創(chuàng)建訂單這個(gè)核心節(jié)點(diǎn)推薦這樣埋點(diǎn)// 文件路徑src/main/java/com/example/order/service/OrderServiceImpl.java Slf4j Service public class OrderServiceImpl implements OrderService { Override public OrderCreateResult createOrder(OrderCreateRequest request) { Long orderId null; long startTime System.currentTimeMillis(); try { log.info([createOrder] 開始創(chuàng)建訂單, userId{}, skuId{}, quantity{}, request.getUserId(), request.getSkuId(), request.getQuantity()); // 業(yè)務(wù)邏輯 orderId doCreateOrder(request); log.info([createOrder] 訂單創(chuàng)建成功, orderId{}, costMs{}, orderId, System.currentTimeMillis() - startTime); return OrderCreateResult.success(orderId); } catch (Exception e) { log.error([createOrder] 訂單創(chuàng)建失敗, userId{}, skuId{}, quantity{}, request.getUserId(), request.getSkuId(), request.getQuantity(), e); throw e; } finally { log.info([createOrder] 訂單創(chuàng)建結(jié)束, orderId{}, costMs{}, orderId, System.currentTimeMillis() - startTime); } } }這個(gè)埋點(diǎn)的好處是日志中能看到入?yún)?、結(jié)果、耗時(shí)失敗時(shí)有異常堆棧同時(shí)保留了上下文參數(shù)costMs可以用于后續(xù)性能分析發(fā)現(xiàn)訂單創(chuàng)建越來越慢時(shí)直接查日志平臺(tái)里createOrder的耗時(shí)趨勢(shì)。5.3 遠(yuǎn)程調(diào)用日志微服務(wù)排障最常遇到的問題是用戶說下單失敗到底是訂單服務(wù)的問題還是庫存服務(wù)的問題還是下游 HTTP 接口的問題。遠(yuǎn)程調(diào)用必須記錄日志而且要記錄全量鏈路信息。// 文件路徑src/main/java/com/example/common/log/RpcLogAspect.java Aspect Component Slf4j public class RpcLogAspect { Around(annotation(com.example.common.log.RpcLog)) public Object around(ProceedingJoinPoint joinPoint) throws Throwable { MethodSignature signature (MethodSignature) joinPoint.getSignature(); Method method signature.getMethod(); RpcLog rpcLog method.getAnnotation(RpcLog.class); String targetService rpcLog.service(); String methodName method.getName(); long start System.currentTimeMillis(); Object result null; try { result joinPoint.proceed(); return result; } catch (Exception e) { log.error([RPC] {}#{} 調(diào)用異常, costMs{}, targetService, methodName, System.currentTimeMillis() - start, e); throw e; } finally { log.info([RPC] {}#{} 調(diào)用完成, result{}, costMs{}, targetService, methodName, JSON.toJSONString(result), System.currentTimeMillis() - start); } } }這里可以給遠(yuǎn)程調(diào)用方法定義注解RpcLog(service inventory-service)切面自動(dòng)記錄遠(yuǎn)程調(diào)用日志。之后排查跨服務(wù)問題時(shí)通過 TraceId 搜日志能直接看到庫存服務(wù)調(diào)用返回了什么結(jié)果耗時(shí)多少。5.4 避免日志打爆磁盤的三個(gè)建議日志不是打得越多越好。生產(chǎn)環(huán)境幾個(gè)典型問題業(yè)務(wù)代碼每行都打日志、循環(huán)體里打日志、打印大對(duì)象導(dǎo)致的日志量爆炸。三個(gè)建議第一不要在 for 循環(huán)中打 INFO 日志。如果循環(huán)一萬次日志會(huì)膨脹一萬倍?？梢栽谘h(huán)結(jié)束后匯總打印一次。第二不要打印整個(gè)大對(duì)象的 toString。比如一個(gè)包含用戶敏感信息的對(duì)象JSON 序列化后可能有幾 KB多打幾次就可能把磁盤或 Kafka 帶寬打爆。第三日志內(nèi)容遵守脫敏要求。密碼、手機(jī)號(hào)、身份證、銀行卡號(hào)等敏感字段打印前必須先脫敏。6. 日志存儲(chǔ)、檢索與可視化日志經(jīng)過采集傳輸后最終落到 ES 中。這一層的設(shè)計(jì)直接決定日志查詢體驗(yàn)。6.1 Elasticsearch 索引策略日志類數(shù)據(jù)的索引策略核心是時(shí)間分區(qū)。根據(jù)日志量選擇按天或按月創(chuàng)建索引。日志量規(guī)模索引策略說明日均 10GB按天分索引數(shù)據(jù)量小查詢效率高日均 10GB-100GB按天分索引 冷熱分離配合 ILM 生命周期管理日均 100GB按小時(shí)分索引控制單個(gè)索引的 shard 規(guī)模推薦使用索引生命周期管理ILM策略自動(dòng)完成熱索引到冷索引的切換以及舊數(shù)據(jù)的清理。6.2 Kibana 檢索技巧日志平臺(tái)搭好后開發(fā)最常用的場(chǎng)景就是按 TraceId 檢索。Kibana Discover 頁面可以這樣查{ query: { bool: { must: [ { term: { traceId.keyword: 4a3f8c90d2e1b7a5 } } ] } } }如果你的日志里 traceId 保存為keyword類型可以用term精確匹配。如果日志是text類型則需要用match。建議在 ES mapping 中把 traceId 設(shè)置為keyword以便精確查詢。6.3 慢查詢與錯(cuò)誤日志單獨(dú)視圖如果所有日志都混在一個(gè)索引里排障時(shí)過濾條件很麻煩。建議在 Kibana 中建立兩個(gè)常用視圖鏈路追蹤視圖按 traceId 反查完整調(diào)用鏈快速判斷故障發(fā)生在哪個(gè)環(huán)節(jié)。錯(cuò)誤告警視圖按 level: ERROR 過濾配合 service、instance 字段在一個(gè)頁面看到所有服務(wù)當(dāng)前的報(bào)錯(cuò)情況。7. 基于日志的監(jiān)控告警日志體系不只是用來事后查日志的更重要的價(jià)值在于及時(shí)發(fā)現(xiàn)潛在故障。7.1 哪些日志需要告警生產(chǎn)環(huán)境的告警要克制只告警需要人處理的問題。推薦設(shè)置四類日志告警告警規(guī)則觸發(fā)條件處理對(duì)象異常堆積告警單服務(wù) ERROR 日志 5 分鐘超過 50 條開發(fā)值班熔斷降級(jí)觸發(fā)告警WARN 日志中出現(xiàn)降級(jí)關(guān)鍵詞開發(fā)值班超時(shí)告警遠(yuǎn)程調(diào)用耗時(shí)超過 2 秒的日志開發(fā) 運(yùn)維日志量異常告警某服務(wù)日志量突增 5 倍排查日志刷屏7.2 基于 ElastAlert 的告警示例ElastAlert 是配合 ES 使用的告警組件。一個(gè)簡(jiǎn)單的高頻錯(cuò)誤告警配置如下# 文件路徑/etc/elastalert/rules/error_rate.yaml name: high-error-rate type: frequency index: micro-service-log-* num_events: 50 timeframe: minutes: 5 filter: - term: level.keyword: ERROR alert: - dingtalk dingtalk_webhook_url: https://oapi.dingtalk.com/robot/send?access_tokenxxx alert_text: 告警微服務(wù)ERROR日志5分鐘超過50條當(dāng) 5 分鐘內(nèi) ERROR 日志超過 50 條時(shí)ElastAlert 推送告警到釘釘或企業(yè)微信。告警的目的是讓故障發(fā)現(xiàn)時(shí)間從用戶反饋?zhàn)兂上到y(tǒng)自動(dòng)告警這是生產(chǎn)級(jí)體系的一個(gè)重要能力。7.3 告警治理告警疲勞問題告警太多容易造成告警疲勞真正的故障反而被淹沒?？梢宰鋈朗諗恳皇欠旨?jí)。P0 告警業(yè)務(wù)不可用、主鏈路異常通知到人P2 告警性能下降、慢查詢只記錄到周報(bào)。二是聚合。同一服務(wù)同一類錯(cuò)誤在 10 分鐘內(nèi)只觸發(fā)一次避免凌晨被幾十條相同告警轟炸。三是去重。告警時(shí)帶上 TraceId 和異常摘要開發(fā)可以直接在日志平臺(tái)定位問題。8. 常見日志排障問題與排查思路日志體系運(yùn)行一段時(shí)間后會(huì)遇到各種問題。以下是我在實(shí)際項(xiàng)目中遇到的幾個(gè)高頻問題。問題現(xiàn)象常見原因解決思路Kibana 搜不到今天的日志Filebeat 未重啟或日志文件路徑不對(duì)檢查 Filebeat 狀態(tài)測(cè)試采集連通性日志里有大量空 traceIdFilter 沒生效或異步線程丟了 MDC檢查 Filter 注冊(cè)順序檢查異步線程池包裝ES 寫入慢導(dǎo)致消息積壓日志量超過 ES 寫入極限增加 ES 節(jié)點(diǎn)或調(diào) Kafka 消費(fèi)并發(fā)日志平臺(tái)查到但格式是純文本應(yīng)用日志輸出格式?jīng)]改成 JSON修改日志配置確認(rèn)輸出為 JSON服務(wù)重啟后老日志丟失日志路徑配置在臨時(shí)目錄把日志目錄掛載到持久化磁盤ERROR 刷屏看不出重點(diǎn)日志級(jí)別用得太泛收窄 ERROR 使用范圍配合過濾視圖8.1 TraceId 丟失問題深入排查TraceId 丟失是日志體系中最常見的問題。排查順序是先看應(yīng)用日志確認(rèn)是完全沒有 TraceId還是部分場(chǎng)景缺失。如果是部分缺失先查是否有Async異步方法或底層線程池。再看過濾器注冊(cè)順序在 Spring Boot 中自定義 Filter 要用Order聲明如果業(yè)務(wù) Filter 在 TraceIdFilter 之前執(zhí)行中間打印日志就沒有 TraceId。最后看服務(wù)間調(diào)用調(diào)用下游時(shí)是否通過 Feign 或 RestTemplate 的攔截器傳遞了 Header。下游服務(wù)如何從頭里取 TraceId 的邏輯也要檢查。8.2 日志量大導(dǎo)致存儲(chǔ)成本高怎么處理生產(chǎn)環(huán)境日志量是所有微服務(wù)團(tuán)隊(duì)的普遍痛點(diǎn)。推薦組合方案降低單條日志體量。去掉 DEBUG 日志縮短 message 內(nèi)容日志中不打印大對(duì)象。生命周期上做冷熱分層。熱數(shù)據(jù)保留 7 天冷數(shù)據(jù)壓縮存儲(chǔ)保留 30 天超過 30 天的日志歸檔到對(duì)象存儲(chǔ)。只保留關(guān)鍵字段的索引。ES 中為所有字段建索引很耗存儲(chǔ)建議對(duì) traceId、service、level、timestamp 這幾個(gè)常用檢索字段建索引其他字段設(shè)為enabled: false。9. 生產(chǎn)級(jí)日志體系落地最佳實(shí)踐最后一個(gè)章節(jié)結(jié)合實(shí)際項(xiàng)目經(jīng)驗(yàn)給出搭建日志體系時(shí)的工程建議。9.1 從最小可用搭建到逐步完善日志體系建設(shè)不建議一步到位。對(duì)于剛開始搭建微服務(wù)框架的團(tuán)隊(duì)分三個(gè)階段推進(jìn)更穩(wěn)妥第一階段先做日志規(guī)范化和 TraceId 鏈路。所有服務(wù)統(tǒng)一日志格式統(tǒng)一輸出 JSON加上 TraceId。這一階段不需要復(fù)雜工具鏈先在本地和測(cè)試環(huán)境驗(yàn)證。第二階段部署 ELK Kafka把日志采集到統(tǒng)一平臺(tái)。這一階段的目標(biāo)是讓所有服務(wù)日志都匯聚到一起能看到全局視角。第三階段加監(jiān)控告警、慢查詢分析、日志量治理。等日志平臺(tái)穩(wěn)定運(yùn)行后再逐步疊加告警規(guī)則和運(yùn)維能力。9.2 日志平臺(tái)排障流程標(biāo)準(zhǔn)化日志體系建好后開發(fā)側(cè)還需要一套標(biāo)準(zhǔn)排障流程。推薦遵循以下順序第一步用戶反饋問題時(shí)先拿訂單號(hào)或用戶 ID去日志平臺(tái)搜相關(guān)業(yè)務(wù)日志拿到 TraceId。第二步按 TraceId 全鏈路檢索看是哪一步出錯(cuò)的。如果調(diào)用下游超時(shí)看下游是否打印了異常。第三步結(jié)合異常堆棧和耗時(shí)數(shù)據(jù)判斷是代碼問題、中間件問題還是網(wǎng)絡(luò)問題。第四步定位到具體服務(wù)后查看該服務(wù)對(duì)應(yīng)實(shí)例的上下文日志補(bǔ)充排障信息。9.3 多環(huán)境日志隔離與權(quán)限控制線上日志涉及敏感信息權(quán)限控制不能省略。不同環(huán)境建議采用不同的索引前綴例如prod-log-、test-log-Kibana 層面用空間或索引權(quán)限隔離。開發(fā)人員默認(rèn)只能看測(cè)試環(huán)境日志生產(chǎn)環(huán)境日志按需申請(qǐng)權(quán)限。賬號(hào)權(quán)限遵循最小化原則不要給所有開發(fā)全量開放。9.4 日志體系也需要混沌演練日志體系本身也是系統(tǒng)也可能掛。生產(chǎn)環(huán)境每隔一段時(shí)間做一次日志平臺(tái)故障演練模擬 Filebeat 掛了會(huì)怎么樣、Kafka 消費(fèi)積壓會(huì)怎么樣、ES 節(jié)點(diǎn)宕機(jī)會(huì)怎么樣。提前發(fā)現(xiàn)問題而不是等 P0 事故時(shí)才第一次面對(duì)。10. 總結(jié)與下一步學(xué)習(xí)路線這套微服務(wù)日志體系的核心思路可以總結(jié)為一句話讓每一次用戶請(qǐng)求都有唯一的 TraceId讓每一行日志都能被結(jié)構(gòu)化采集讓每一個(gè)異常都能在日志平臺(tái)上被快速檢索和告警。文中相關(guān)內(nèi)容比較簡(jiǎn)單可以直接對(duì)照實(shí)踐先統(tǒng)一日志規(guī)范把 Logback 輸出改成 JSON 格式讓日志具備結(jié)構(gòu)化能力。再實(shí)現(xiàn) TraceId 過濾器和服務(wù)間傳遞保證一次請(qǐng)求全鏈路日志可串聯(lián)。然后部署 Filebeat Kafka Logstash ES Kibana讓日志從分散的服務(wù)器匯聚到統(tǒng)一平臺(tái)。最后在平臺(tái)層加檢索視圖和告警規(guī)則讓故障從“用戶發(fā)現(xiàn)”變成“系統(tǒng)發(fā)現(xiàn)”。對(duì)于正在從零搭建微服務(wù)框架的讀者日志體系建設(shè)不需要排在業(yè)務(wù)開發(fā)之后建議服務(wù)拆分一開始就同步做好日志規(guī)范。等系統(tǒng)真正上線后你會(huì)發(fā)現(xiàn)這套體系的價(jià)值遠(yuǎn)超預(yù)期——它是排障的底座也是穩(wěn)定性保障的地基。