微服務架構解決了單體應用擴展難的問題卻把排障難度轉移到了日志和鏈路追蹤上。一次用戶請求跨越多個服務、多個數據庫、多個中間件任何一個環節超時或報錯都需要從分散日志中還原現場。如果日志體系沒有設計好排障就變成低效的人工 grep。微服務日志體系不是簡單地接一個采集工具而是一套覆蓋日志產生、規范、采集、傳輸、存儲、檢索、告警和治理的完整鏈路。這里會先講清楚排障難點再逐步展開一套可落地的生產級日志體系設計。1. 為什么微服務排障難日志體系要解決什么問題1.1 微服務排障的三類典型困境第一類困境是日志分散。單體應用時代一個請求的完整執行過程基本都在同一個進程里日志文件也相對集中。微服務化之后一個請求可能要經過網關、用戶服務、訂單服務、支付服務、消息消費者每個服務可能還有多個實例。日志散落在不同機器、不同容器、不同目錄里沒有統一線索時很難把一次請求串起來。第二類困境是格式不統一。不同團隊寫的服務可能有的用 logback有的用 log4j2有的直接System.out.println。日志時間有的用本地時間有的用 UTC有的沒有毫秒。字段命名也各不相同userId和user_id同時存在。排障時每次都要先理解日志格式再去過濾效率很低。第三類困境是日志量大。微服務實例一多日志量會快速膨脹。如果直接全文檢索查詢會越來越慢如果不做索引生命周期管理磁盤遲早被寫滿。到了大促或故障高峰期日志系統本身也可能成為瓶頸反而拖慢業務恢復。1.2 生產級日志體系的目標所謂生產級不是日志采集工具能跑起來就行而是必須滿足幾個基本要求。請求有鏈路標識。入口生成 traceId下游服務通過調用鏈透傳日志中能根據 traceId 查到一個請求的完整路徑。日志格式可解析。日志輸出為結構化字段而不是只有一段模糊的文本。至少包含時間、級別、服務名、實例、traceId、業務消息和異常信息。日志延遲可控。從業務寫日志到 Elasticsearch 可檢索延遲需要在一定范圍比如分鐘級以內。不能經常出現日志丟失或幾個小時后才看到日志。日志有生命周期。熱數據保留幾天冷數據保留更長時間超過保留周期的數據要自動刪除或歸檔而不是等磁盤告警后手工清理。日志系統本身不能影響業務。應用寫日志是異步的采集鏈路故障時不能阻塞業務線程。生產級體系還要關注采集組件狀態、Kafka 消費堆積和 ES 磁盤水位。2. 設計日志體系前先把日志規范定下來日志規范是整套體系的地基。如果每個服務輸出的字段都不一樣后面接 Filebeat、Kafka、Logstash、Elasticsearch 都會很被動。排障效率提升的第一步不是工具而是標準。2.1 統一日志字段讓檢索有依據建議服務端日志統一輸出為 JSON 格式。每條日志的頂層字段盡量固定下面是一組常見字段。字段類型含義示例timestampstring日志產生時間2026-06-01T10:00:00.123Zlevelstring日志級別ERRORservicestring服務名order-serviceinstancestring實例標識10.0.0.1:8080traceIdstring鏈路ID8f3a1b2c...methodstring請求方法POSTuristring請求路徑/api/orderstatusintHTTP 狀態碼500costMsint接口耗時毫秒128userIdstring用戶標識u_10001messagestring業務消息訂單創建失敗exceptionstring異常棧原文java.lang.NullPointerException...字段不是越多越好但上面這些基礎字段能覆蓋大部分排障場景。service用于區分系統instance用于還原具體實例traceId用于串聯調用鏈costMs用于定位性能問題exception用于快速搜索異常棧。實際項目里團隊可以先定一個最小字段集發布到協作文檔或代碼倉庫的模板中。新服務開發時必須按這套字段輸出老服務逐步遷移。不要指望所有服務一天改完但至少要有一個明確的規范版本。2.2 日志級別怎么定避免日志噪音日志級別是排障時最重要的過濾維度之一。級別定得不好會帶來兩種典型問題把 ERROR 當普通日志打告警全是噪音或者把 DEBUG 打到生產日志量爆炸真正有用的 ERROR 被淹沒。級別使用場景生產預期ERROR業務失敗、異常導致流程中斷需要人工介入保留并告警WARN可以恢復但不正常比如緩存穿透、重試成功保留不直接告警INFO關鍵流程節點比如訂單創建、支付回調保留但要控制頻率DEBUG排查細節數據默認關閉按需開啟TRACE內部調用鏈細節很少開啟一個簡單判斷標準如果某條日志打出來之后值班同學不用看那它就不該是 ERROR。ERROR 應該對應一個需要關注的失敗事實而不是每次 catch 異常都打 ERROR。2.3 TraceID 貫穿始終從一次請求還原完整路徑TraceID 是微服務日志體系里最重要的字段。它的作用很簡單一次外部請求進入系統時生成一個唯一 ID之后所有服務在處理這個請求時都攜帶這個 ID并寫入各自日志。排障時只要搜索這個 ID就能得到完整請求鏈路。常見做法是在網關或入口 Filter 中生成 TraceID并通過 HTTP Header 向下游傳遞。比如統一使用X-Trace-Id作為透傳 Header。以 Servlet 場景為例可以用一個 Filter 在入口生成并寫入 MDC。public class TraceIdFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { String traceId ((HttpServletRequest) request).getHeader(X-Trace-Id); if (traceId null || traceId.isEmpty()) { traceId UUID.randomUUID().toString().replace(-, ); } MDC.put(traceId, traceId); try { ((HttpServletResponse) response).setHeader(X-Trace-Id, traceId); chain.doFilter(request, response); } finally { MDC.remove(traceId); } } }MDC.remove很重要。線程池中的線程會被復用如果不清理下一條請求可能拿到上一個請求的 traceId導致日志串鏈路。下游服務在發起遠程調用時要把 traceId 繼續傳遞下去。HttpHeaders headers new HttpHeaders(); if (MDC.get(traceId) ! null) { headers.set(X-Trace-Id, MDC.get(traceId)); }使用異步線程池時MDC 不會自動傳遞。如果是 SpringThreadPoolTaskExecutor可以通過TaskDecorator在提交任務時拷貝 MDC執行完后恢復如果只是在代碼里手動new Thread則需要手工 put 和 remove。日志框架側也要把 traceId 輸出到結構化字段中。使用logstash-logback-encoder時encoder 會自動包含 MDC 中的字段。以 logback 為例一個最小 JSON 輸出配置如下。configuration appender nameJSON_FILE classch.qos.logback.core.rolling.RollingFileAppender file/data/logs/order-service/app.log/file rollingPolicy classch.qos.logback.core.rolling.TimeBasedRollingPolicy fileNamePattern/data/logs/order-service/app.%d{yyyy-MM-dd}.log/fileNamePattern maxHistory7/maxHistory /rollingPolicy encoder classnet.logstash.logback.encoder.LogstashEncoder includeMdctrue/includeMdc customFields{service:order-service,env:prod}/customFields /encoder /appender root levelINFO appender-ref refJSON_FILE/ /root /configuration這里把service和env固定寫進了應用日志配置避免了每個服務在業務代碼里重復拼接。不同版本 encoder 的配置略有差異落地前先確認依賴版本。3. 日志采集層從服務本地日志到統一通道日志規范定好后下一個問題是日志怎么從應用進程到達統一的日志中心。生產環境常見的方案是應用寫本地文件Filebeat 采集文件輸出到 Kafka。3.1 本地文件采集和直接上報怎么選有些新項目會直接在應用里用 HTTP 或 SDK 把日志發送到 Logstash 或 Kafka。這種方式接入快但客戶端邏輯重還要處理發送失敗、緩沖區溢出、網絡抖動等問題。應用本身已經有業務邏輯再承擔完整的日志傳輸職責容易引入不穩定因素。更穩妥的組合是應用只負責把結構化日志寫到本地磁盤采集器負責讀文件和傳輸。Filebeat 是常用選擇它輕量、內存開銷小、支持斷點續采適合部署在應用實例旁邊。采集端故障時應用日志仍然寫在本地文件不會立刻丟失。這相當于給日志多了一層本地緩沖。學習環境可以直接看控制臺或tail -f日志文件生產環境建議走文件采集。直接上報適合日志量不大、團隊能接受客戶端 SDK 維護成本的場景但不是默認首選。3.2 Filebeat 采集配置示例Filebeat 配置由 input 和 output 兩部分組成。下面是一個把訂單服務日志采集到 Kafka 的示例。filebeat.inputs: - type: filestream id: order-service-app enabled: true paths: - /data/logs/order-service/*.log fields: service: order-service env: prod fields_under_root: true processors: - add_host_metadata: ~ output.kafka: hosts: [kafka01:9092, kafka02:9092, kafka03:9092] topic: app-log partition: round_robin: reachable_only: true required_acks: 1 compression: gzip max_message_bytes: 1048576paths指定日志文件位置推薦一個 input 只匹配一個服務的日志。fields用于給日志打上服務名和環境標簽fields_under_root: true讓這些字段出現在日志頂層。add_host_metadata會把主機名和 IP 加進來方便按實例過濾。output.kafka中的required_acks: 1表示 Kafka leader 寫入成功即可返回性能和可靠性比較均衡。compression: gzip可以降低網絡帶寬但會增加一點 CPU 開銷。日志量很大時這個權衡通常值得。如果 Filebeat 版本較舊可能沒有filestream需要使用loginput。接入前先確認版本不同版本的配置語法有差異。3.3 采集層最容易踩的坑第一個坑是多個服務共享同一個日志目錄。比如把所有服務的日志都寫到/data/logs/app.logFilebeat 采集后只能打同一個service標簽無法區分來源。推薦按服務隔離目錄比如/data/logs/{service}/app.log。第二個坑是 Filebeat 重復采集滾動日志。應用日志按天滾動后舊文件可能被改名成app.2026-06-01.log。如果 Filebeat 的 path 使用*.log可能把滾動文件和新文件同時采集產生重復。建議嚴格約定文件名規則并在采集配置里避免把歸檔目錄包含進來。第三個坑是采集延遲的假象。業務日志已經寫到文件但 Filebeat 的ignore_older或close_inactive配置過大導致新日志不能及時讀取。排查時不要只看應用日志有沒有寫還要看 Filebeat 是否處于運行狀態、是否報權限錯誤。4. 日志傳輸管道如何保證日志不丟不堵日志量是有峰值的。大促、秒殺、定時任務集中執行時日志寫入速率可能瞬間翻幾倍。如果所有采集器直接把日志寫到 ElasticsearchES 寫入壓力會很大。引入 Kafka 作為緩沖是生產級日志體系里常見的解耦手段。4.1 Kafka 緩沖的作用和關鍵參數Kafka 在日志鏈路中負責削峰填谷。Filebeat 寫入 Kafka 后下游 Logstash 或消費程序可以按照自己的節奏消費不會因為業務流量突增而丟日志。Topic 設計時可以只建一個app-log主題通過日志中的service字段區分服務。也可以按環境分主題比如app-log-prod和app-log-test。分區數要結合下游消費并發決定。單個分區只能被同一個消費組里的一個線程消費分區太少消費并發上不去分區太多Kafka 元數據開銷也會變大。副本數建議生產環境至少 3并配置min.insync.replicas防止部分節點故障時寫入丟失。retention.ms可以設置日志在 Kafka 中的保留時間給下游鏈路故障留出恢復窗口。常見設置是保留 24 到 72 小時具體要看磁盤成本和團隊對日志完整性的要求。分區 key 的選擇也要考慮。如果希望同一實例的日志順序保持有序可以使用instance作為 key如果只關心吞吐可以使用輪詢策略?？绶瞻?traceId 聚合到同一分區意義不大因為查詢階段已經在 ES 中完成聚合不需要在消息隊列里強制同分區。4.2 Logstash 消費和寫入 ElasticsearchLogstash 在整個鏈路里負責消費 Kafka 消息、解析字段、補充信息再批量寫入 Elasticsearch。由于應用側已經輸出 JSON 日志Logstash 的 filter 可以保持很輕不需要用復雜的 grok 正則去切文本。一個最小 pipeline 配置如下。input { kafka { bootstrap_servers kafka01:9092,kafka02:9092 topics [app-log] group_id logstash-app-log codec json consumer_threads 6 } } filter { date { match [timestamp, ISO8601] target timestamp } if [exception] { mutate { add_field { error_flag true } } } } output { elasticsearch { hosts [http://es-data01:9200, http://es-data02:9200] index app-log-%{YYYY.MM.dd} } }codec json表示消息體本身就是 JSON。datefilter 把日志里的timestamp解析成 ES 使用的timestamp字段。error_flag是為了后續檢索時快速過濾異常日志。如果應用日志里混入非 JSON 行比如System.out.println或啟動 Bannercodec json會導致解析失敗。這個問題最好在應用層解決統一使用 logger 輸出不要混用標準輸出。如果無法避免可以改用純文本采集或獨立 topic再用 grok 解析。4.3 消費堆積和背壓處理Kafka 消費堆積是日志鏈路最常見的故障。現象是 Kibana 里最新日志遲遲不出現kafka-consumer-groups顯示的LAG持續增長。處理順序不要亂。先確認是上游寫入變快還是下游消費變慢。如果只是瞬時峰值可以等待消費追平如果持續堆積優先擴容 Logstash 消費吞吐也就是增加分區數和consumer_threads。但不要無限增加線程因為最終瓶頸可能在 ES 寫入。ES 寫入壓力大時會表現為拒絕寫入或寫入耗時上升。這時要檢查 ES 集群的寫入隊列、磁盤水位和 bulk 大小。生產環境建議將 ES 節點角色拆分數據節點和協調節點分離避免高負載互相影響。還要給 ES 設置合理的索引分片數分片過少無法充分利用多節點過多會帶來資源浪費。注意Kafka 消費堆積本身不一定是故障如果業務日志量確實超過正常水位優先擴容而不是清空堆積。清空堆積會丟掉排障現場這是最不建議的做法。5. 日志存儲與檢索ES 索引設計決定查詢速度日志進入 Elasticsearch 之后能不能快速查出來取決于索引設計和字段映射。生產環境見過太多“索引大了查不動”的問題根源往往是最初沒有做索引規劃。5.1 按時間分索引避免單索引無限增長日志天然是和時間強相關的數據。按天建立索引比如app-log-2026.06.01是最常見的做法。好處很明顯查詢最近一天的數據只需要掃描當天索引刪除過期數據只需刪除舊索引不用在單個大索引里做復雜清理。索引別名也可以配合使用。比如查詢最近 7 天日志時可以搜索app-log-*寫入側使用app-log-write別名由 ILM 管理實際索引。這樣可以保持查詢和寫入的穩定。索引分片數要根據數據量和節點數預估。一個分片通常建議控制在 30GB 到 50GB 以內。按天索引時如果每天日志量很大可以按天索引并配置多分片如果每天只有幾百 MB一個分片或少量分片就夠了。5.2 字段映射決定你是過濾還是全文搜索ES 中的字段類型直接影響查詢方式。精確匹配和聚合統計要使用keyword類型模糊匹配和關鍵詞搜索要使用text類型。排障中常用的service、level、traceId、instance、status都應該設計為keyword或數值類型。一個參考 mapping 如下。{ mappings: { properties: { timestamp: { type: date }, level: { type: keyword }, service: { type: keyword }, instance: { type: keyword }, traceId: { type: keyword }, method: { type: keyword }, uri: { type: keyword }, status: { type: integer }, costMs: { type: long }, message: { type: text, fields: { keyword: { type: keyword, ignore_above: 256 } } }, exception: { type: text } } } }message使用text是為了支持關鍵詞搜索同時加了一個keyword子字段方便對短消息做精確過濾。exception使用text但要注意異常棧內容很長不建議在 ES 中對全文做復雜聚合。如果日志字段不固定建議關閉動態 mapping 或使用 dynamic template 白名單。大量動態字段會導致索引 mapping 膨脹嚴重時甚至讓集群停止寫入。統一日志字段規范也是保護 ES 的一個手段。5.3 索引生命周期管理避免磁盤被打滿索引生命周期管理ILM是生產級日志存儲的必需環節。通過 ILM可以讓索引從熱階段滾動到暖階段再按策略刪除。下面是一個簡單的 ILM 策略索引達到 50GB 或 7 天時滾動超過 30 天的索引自動刪除。PUT _ilm/policy/app-log-policy { policy: { phases: { hot: { min_age: 0ms, actions: { rollover: { max_size: 50gb, max_age: 7d } } }, delete: { min_age: 30d, actions: { delete: {} } } } } }ILM 需要配合索引模板使用把策略綁定到對應索引模式上。PUT _index_template/app-log-template { index_patterns: [app-log-*], template: { settings: { number_of_shards: 3, number_of_replicas: 1, index.lifecycle.name: app-log-policy, index.lifecycle.rollover_alias: app-log-write } } }如果使用 ILM 的 Rollover寫入側應使用別名app-log-write查詢則使用app-log-*。日志保留周期的選擇要結合業務需求ERROR 日志可以保留更久普通 INFO 日志保留 7 到 15 天通常就夠。注意不要只設置 ILM 而忽略磁盤容量評估。保留 30 天日志至少要把每天日志量乘以 30 乘以副本數再算上 ES 索引膨脹和 overhead才能確認集群容量是否夠用。6. 排障實戰從一條報警到根因定位的完整鏈路日志體系設計得再好最終還是要回歸到排障場景。用一個常見例子說明凌晨收到告警訂單服務 ERROR 增多接口 P99 升高。這時候應該怎么查。6.1 先用時間和級別縮小范圍不要盲目搜全文排障第一步不是搜具體異常棧而是確定影響范圍。在 Kibana 中使用時間范圍過濾最近 15 分鐘再疊加服務名和級別。service:order-service AND level:ERROR AND timestamp now-15m如果日志量仍然很大可以加上uri或status進一步縮小范圍。比如只查看POST /api/order的錯誤日志。service:order-service AND level:ERROR AND uri:/api/order AND timestamp now-15m排序按timestamp升序先看最早的異常因為第一個異常往往是后續大量錯誤的源頭。如果看到Connection timed out或Read timed out要意識到這可能是下游依賴導致的連鎖反應先找出被調用方是否也有異常。6.2 用 TraceID 串聯完整調用鏈確定一條典型錯誤日志后復制其中的traceId在 Kibana 中搜索。traceId:8f3a1b2c3d4e5f6a7b8c搜索時不限制服務名。只要 TraceID 在所有服務間透傳正確就能查到這個請求經過的所有服務、所有實例的日志。按時間順序排列后可以看到請求從網關進入訂單服務然后調用支付服務最后在哪里耗時最長。日志中會看到類似這樣的關鍵點訂單服務日志顯示調用支付服務開始和結束。支付服務日志顯示處理耗時超過 3 秒。支付服務之后出現數據庫超時或連接池等待。這一步的核心是確認異常發生位置而不是只看最外層報錯。外層的RestClientException可能只是下游超時的表象根因在支付服務的數據庫連接或 SQL 執行上。6.3 從異常日志特征定位根因類型不同錯誤特征對應不同排查方向整理成速查表會很有用。日志特征可能根因下一步檢查status500 大量異常棧服務內部異常看異常棧、線程池、連接池Connection timed out網絡不通或連接池耗盡檢查目標服務、端口、連接池配置Read timed out下游處理慢查看下游服務耗時、GC、慢 SQLlock wait timeout exceeded數據庫鎖競爭查數據庫事務、慢 SQL、死鎖日志OutOfMemoryError內存不足或泄漏查看對堆配置、GC 日志和 微服務日志體系設計：從規范到排障的完整實踐
微服務架構解決了單體應用擴展難的問題卻把排障難度轉移到了日志和鏈路追蹤上。一次用戶請求跨越多個服務、多個數據庫、多個中間件任何一個環節超時或報錯都需要從分散日志中還原現場。如果日志體系沒有設計好排障就變成低效的人工 grep。微服務日志體系不是簡單地接一個采集工具而是一套覆蓋日志產生、規范、采集、傳輸、存儲、檢索、告警和治理的完整鏈路。這里會先講清楚排障難點再逐步展開一套可落地的生產級日志體系設計。1. 為什么微服務排障難日志體系要解決什么問題1.1 微服務排障的三類典型困境第一類困境是日志分散。單體應用時代一個請求的完整執行過程基本都在同一個進程里日志文件也相對集中。微服務化之后一個請求可能要經過網關、用戶服務、訂單服務、支付服務、消息消費者每個服務可能還有多個實例。日志散落在不同機器、不同容器、不同目錄里沒有統一線索時很難把一次請求串起來。第二類困境是格式不統一。不同團隊寫的服務可能有的用 logback有的用 log4j2有的直接System.out.println。日志時間有的用本地時間有的用 UTC有的沒有毫秒。字段命名也各不相同userId和user_id同時存在。排障時每次都要先理解日志格式再去過濾效率很低。第三類困境是日志量大。微服務實例一多日志量會快速膨脹。如果直接全文檢索查詢會越來越慢如果不做索引生命周期管理磁盤遲早被寫滿。到了大促或故障高峰期日志系統本身也可能成為瓶頸反而拖慢業務恢復。1.2 生產級日志體系的目標所謂生產級不是日志采集工具能跑起來就行而是必須滿足幾個基本要求。請求有鏈路標識。入口生成 traceId下游服務通過調用鏈透傳日志中能根據 traceId 查到一個請求的完整路徑。日志格式可解析。日志輸出為結構化字段而不是只有一段模糊的文本。至少包含時間、級別、服務名、實例、traceId、業務消息和異常信息。日志延遲可控。從業務寫日志到 Elasticsearch 可檢索延遲需要在一定范圍比如分鐘級以內。不能經常出現日志丟失或幾個小時后才看到日志。日志有生命周期。熱數據保留幾天冷數據保留更長時間超過保留周期的數據要自動刪除或歸檔而不是等磁盤告警后手工清理。日志系統本身不能影響業務。應用寫日志是異步的采集鏈路故障時不能阻塞業務線程。生產級體系還要關注采集組件狀態、Kafka 消費堆積和 ES 磁盤水位。2. 設計日志體系前先把日志規范定下來日志規范是整套體系的地基。如果每個服務輸出的字段都不一樣后面接 Filebeat、Kafka、Logstash、Elasticsearch 都會很被動。排障效率提升的第一步不是工具而是標準。2.1 統一日志字段讓檢索有依據建議服務端日志統一輸出為 JSON 格式。每條日志的頂層字段盡量固定下面是一組常見字段。字段類型含義示例timestampstring日志產生時間2026-06-01T10:00:00.123Zlevelstring日志級別ERRORservicestring服務名order-serviceinstancestring實例標識10.0.0.1:8080traceIdstring鏈路ID8f3a1b2c...methodstring請求方法POSTuristring請求路徑/api/orderstatusintHTTP 狀態碼500costMsint接口耗時毫秒128userIdstring用戶標識u_10001messagestring業務消息訂單創建失敗exceptionstring異常棧原文java.lang.NullPointerException...字段不是越多越好但上面這些基礎字段能覆蓋大部分排障場景。service用于區分系統instance用于還原具體實例traceId用于串聯調用鏈costMs用于定位性能問題exception用于快速搜索異常棧。實際項目里團隊可以先定一個最小字段集發布到協作文檔或代碼倉庫的模板中。新服務開發時必須按這套字段輸出老服務逐步遷移。不要指望所有服務一天改完但至少要有一個明確的規范版本。2.2 日志級別怎么定避免日志噪音日志級別是排障時最重要的過濾維度之一。級別定得不好會帶來兩種典型問題把 ERROR 當普通日志打告警全是噪音或者把 DEBUG 打到生產日志量爆炸真正有用的 ERROR 被淹沒。級別使用場景生產預期ERROR業務失敗、異常導致流程中斷需要人工介入保留并告警WARN可以恢復但不正常比如緩存穿透、重試成功保留不直接告警INFO關鍵流程節點比如訂單創建、支付回調保留但要控制頻率DEBUG排查細節數據默認關閉按需開啟TRACE內部調用鏈細節很少開啟一個簡單判斷標準如果某條日志打出來之后值班同學不用看那它就不該是 ERROR。ERROR 應該對應一個需要關注的失敗事實而不是每次 catch 異常都打 ERROR。2.3 TraceID 貫穿始終從一次請求還原完整路徑TraceID 是微服務日志體系里最重要的字段。它的作用很簡單一次外部請求進入系統時生成一個唯一 ID之后所有服務在處理這個請求時都攜帶這個 ID并寫入各自日志。排障時只要搜索這個 ID就能得到完整請求鏈路。常見做法是在網關或入口 Filter 中生成 TraceID并通過 HTTP Header 向下游傳遞。比如統一使用X-Trace-Id作為透傳 Header。以 Servlet 場景為例可以用一個 Filter 在入口生成并寫入 MDC。public class TraceIdFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { String traceId ((HttpServletRequest) request).getHeader(X-Trace-Id); if (traceId null || traceId.isEmpty()) { traceId UUID.randomUUID().toString().replace(-, ); } MDC.put(traceId, traceId); try { ((HttpServletResponse) response).setHeader(X-Trace-Id, traceId); chain.doFilter(request, response); } finally { MDC.remove(traceId); } } }MDC.remove很重要。線程池中的線程會被復用如果不清理下一條請求可能拿到上一個請求的 traceId導致日志串鏈路。下游服務在發起遠程調用時要把 traceId 繼續傳遞下去。HttpHeaders headers new HttpHeaders(); if (MDC.get(traceId) ! null) { headers.set(X-Trace-Id, MDC.get(traceId)); }使用異步線程池時MDC 不會自動傳遞。如果是 SpringThreadPoolTaskExecutor可以通過TaskDecorator在提交任務時拷貝 MDC執行完后恢復如果只是在代碼里手動new Thread則需要手工 put 和 remove。日志框架側也要把 traceId 輸出到結構化字段中。使用logstash-logback-encoder時encoder 會自動包含 MDC 中的字段。以 logback 為例一個最小 JSON 輸出配置如下。configuration appender nameJSON_FILE classch.qos.logback.core.rolling.RollingFileAppender file/data/logs/order-service/app.log/file rollingPolicy classch.qos.logback.core.rolling.TimeBasedRollingPolicy fileNamePattern/data/logs/order-service/app.%d{yyyy-MM-dd}.log/fileNamePattern maxHistory7/maxHistory /rollingPolicy encoder classnet.logstash.logback.encoder.LogstashEncoder includeMdctrue/includeMdc customFields{service:order-service,env:prod}/customFields /encoder /appender root levelINFO appender-ref refJSON_FILE/ /root /configuration這里把service和env固定寫進了應用日志配置避免了每個服務在業務代碼里重復拼接。不同版本 encoder 的配置略有差異落地前先確認依賴版本。3. 日志采集層從服務本地日志到統一通道日志規范定好后下一個問題是日志怎么從應用進程到達統一的日志中心。生產環境常見的方案是應用寫本地文件Filebeat 采集文件輸出到 Kafka。3.1 本地文件采集和直接上報怎么選有些新項目會直接在應用里用 HTTP 或 SDK 把日志發送到 Logstash 或 Kafka。這種方式接入快但客戶端邏輯重還要處理發送失敗、緩沖區溢出、網絡抖動等問題。應用本身已經有業務邏輯再承擔完整的日志傳輸職責容易引入不穩定因素。更穩妥的組合是應用只負責把結構化日志寫到本地磁盤采集器負責讀文件和傳輸。Filebeat 是常用選擇它輕量、內存開銷小、支持斷點續采適合部署在應用實例旁邊。采集端故障時應用日志仍然寫在本地文件不會立刻丟失。這相當于給日志多了一層本地緩沖。學習環境可以直接看控制臺或tail -f日志文件生產環境建議走文件采集。直接上報適合日志量不大、團隊能接受客戶端 SDK 維護成本的場景但不是默認首選。3.2 Filebeat 采集配置示例Filebeat 配置由 input 和 output 兩部分組成。下面是一個把訂單服務日志采集到 Kafka 的示例。filebeat.inputs: - type: filestream id: order-service-app enabled: true paths: - /data/logs/order-service/*.log fields: service: order-service env: prod fields_under_root: true processors: - add_host_metadata: ~ output.kafka: hosts: [kafka01:9092, kafka02:9092, kafka03:9092] topic: app-log partition: round_robin: reachable_only: true required_acks: 1 compression: gzip max_message_bytes: 1048576paths指定日志文件位置推薦一個 input 只匹配一個服務的日志。fields用于給日志打上服務名和環境標簽fields_under_root: true讓這些字段出現在日志頂層。add_host_metadata會把主機名和 IP 加進來方便按實例過濾。output.kafka中的required_acks: 1表示 Kafka leader 寫入成功即可返回性能和可靠性比較均衡。compression: gzip可以降低網絡帶寬但會增加一點 CPU 開銷。日志量很大時這個權衡通常值得。如果 Filebeat 版本較舊可能沒有filestream需要使用loginput。接入前先確認版本不同版本的配置語法有差異。3.3 采集層最容易踩的坑第一個坑是多個服務共享同一個日志目錄。比如把所有服務的日志都寫到/data/logs/app.logFilebeat 采集后只能打同一個service標簽無法區分來源。推薦按服務隔離目錄比如/data/logs/{service}/app.log。第二個坑是 Filebeat 重復采集滾動日志。應用日志按天滾動后舊文件可能被改名成app.2026-06-01.log。如果 Filebeat 的 path 使用*.log可能把滾動文件和新文件同時采集產生重復。建議嚴格約定文件名規則并在采集配置里避免把歸檔目錄包含進來。第三個坑是采集延遲的假象。業務日志已經寫到文件但 Filebeat 的ignore_older或close_inactive配置過大導致新日志不能及時讀取。排查時不要只看應用日志有沒有寫還要看 Filebeat 是否處于運行狀態、是否報權限錯誤。4. 日志傳輸管道如何保證日志不丟不堵日志量是有峰值的。大促、秒殺、定時任務集中執行時日志寫入速率可能瞬間翻幾倍。如果所有采集器直接把日志寫到 ElasticsearchES 寫入壓力會很大。引入 Kafka 作為緩沖是生產級日志體系里常見的解耦手段。4.1 Kafka 緩沖的作用和關鍵參數Kafka 在日志鏈路中負責削峰填谷。Filebeat 寫入 Kafka 后下游 Logstash 或消費程序可以按照自己的節奏消費不會因為業務流量突增而丟日志。Topic 設計時可以只建一個app-log主題通過日志中的service字段區分服務。也可以按環境分主題比如app-log-prod和app-log-test。分區數要結合下游消費并發決定。單個分區只能被同一個消費組里的一個線程消費分區太少消費并發上不去分區太多Kafka 元數據開銷也會變大。副本數建議生產環境至少 3并配置min.insync.replicas防止部分節點故障時寫入丟失。retention.ms可以設置日志在 Kafka 中的保留時間給下游鏈路故障留出恢復窗口。常見設置是保留 24 到 72 小時具體要看磁盤成本和團隊對日志完整性的要求。分區 key 的選擇也要考慮。如果希望同一實例的日志順序保持有序可以使用instance作為 key如果只關心吞吐可以使用輪詢策略?？绶瞻?traceId 聚合到同一分區意義不大因為查詢階段已經在 ES 中完成聚合不需要在消息隊列里強制同分區。4.2 Logstash 消費和寫入 ElasticsearchLogstash 在整個鏈路里負責消費 Kafka 消息、解析字段、補充信息再批量寫入 Elasticsearch。由于應用側已經輸出 JSON 日志Logstash 的 filter 可以保持很輕不需要用復雜的 grok 正則去切文本。一個最小 pipeline 配置如下。input { kafka { bootstrap_servers kafka01:9092,kafka02:9092 topics [app-log] group_id logstash-app-log codec json consumer_threads 6 } } filter { date { match [timestamp, ISO8601] target timestamp } if [exception] { mutate { add_field { error_flag true } } } } output { elasticsearch { hosts [http://es-data01:9200, http://es-data02:9200] index app-log-%{YYYY.MM.dd} } }codec json表示消息體本身就是 JSON。datefilter 把日志里的timestamp解析成 ES 使用的timestamp字段。error_flag是為了后續檢索時快速過濾異常日志。如果應用日志里混入非 JSON 行比如System.out.println或啟動 Bannercodec json會導致解析失敗。這個問題最好在應用層解決統一使用 logger 輸出不要混用標準輸出。如果無法避免可以改用純文本采集或獨立 topic再用 grok 解析。4.3 消費堆積和背壓處理Kafka 消費堆積是日志鏈路最常見的故障。現象是 Kibana 里最新日志遲遲不出現kafka-consumer-groups顯示的LAG持續增長。處理順序不要亂。先確認是上游寫入變快還是下游消費變慢。如果只是瞬時峰值可以等待消費追平如果持續堆積優先擴容 Logstash 消費吞吐也就是增加分區數和consumer_threads。但不要無限增加線程因為最終瓶頸可能在 ES 寫入。ES 寫入壓力大時會表現為拒絕寫入或寫入耗時上升。這時要檢查 ES 集群的寫入隊列、磁盤水位和 bulk 大小。生產環境建議將 ES 節點角色拆分數據節點和協調節點分離避免高負載互相影響。還要給 ES 設置合理的索引分片數分片過少無法充分利用多節點過多會帶來資源浪費。注意Kafka 消費堆積本身不一定是故障如果業務日志量確實超過正常水位優先擴容而不是清空堆積。清空堆積會丟掉排障現場這是最不建議的做法。5. 日志存儲與檢索ES 索引設計決定查詢速度日志進入 Elasticsearch 之后能不能快速查出來取決于索引設計和字段映射。生產環境見過太多“索引大了查不動”的問題根源往往是最初沒有做索引規劃。5.1 按時間分索引避免單索引無限增長日志天然是和時間強相關的數據。按天建立索引比如app-log-2026.06.01是最常見的做法。好處很明顯查詢最近一天的數據只需要掃描當天索引刪除過期數據只需刪除舊索引不用在單個大索引里做復雜清理。索引別名也可以配合使用。比如查詢最近 7 天日志時可以搜索app-log-*寫入側使用app-log-write別名由 ILM 管理實際索引。這樣可以保持查詢和寫入的穩定。索引分片數要根據數據量和節點數預估。一個分片通常建議控制在 30GB 到 50GB 以內。按天索引時如果每天日志量很大可以按天索引并配置多分片如果每天只有幾百 MB一個分片或少量分片就夠了。5.2 字段映射決定你是過濾還是全文搜索ES 中的字段類型直接影響查詢方式。精確匹配和聚合統計要使用keyword類型模糊匹配和關鍵詞搜索要使用text類型。排障中常用的service、level、traceId、instance、status都應該設計為keyword或數值類型。一個參考 mapping 如下。{ mappings: { properties: { timestamp: { type: date }, level: { type: keyword }, service: { type: keyword }, instance: { type: keyword }, traceId: { type: keyword }, method: { type: keyword }, uri: { type: keyword }, status: { type: integer }, costMs: { type: long }, message: { type: text, fields: { keyword: { type: keyword, ignore_above: 256 } } }, exception: { type: text } } } }message使用text是為了支持關鍵詞搜索同時加了一個keyword子字段方便對短消息做精確過濾。exception使用text但要注意異常棧內容很長不建議在 ES 中對全文做復雜聚合。如果日志字段不固定建議關閉動態 mapping 或使用 dynamic template 白名單。大量動態字段會導致索引 mapping 膨脹嚴重時甚至讓集群停止寫入。統一日志字段規范也是保護 ES 的一個手段。5.3 索引生命周期管理避免磁盤被打滿索引生命周期管理ILM是生產級日志存儲的必需環節。通過 ILM可以讓索引從熱階段滾動到暖階段再按策略刪除。下面是一個簡單的 ILM 策略索引達到 50GB 或 7 天時滾動超過 30 天的索引自動刪除。PUT _ilm/policy/app-log-policy { policy: { phases: { hot: { min_age: 0ms, actions: { rollover: { max_size: 50gb, max_age: 7d } } }, delete: { min_age: 30d, actions: { delete: {} } } } } }ILM 需要配合索引模板使用把策略綁定到對應索引模式上。PUT _index_template/app-log-template { index_patterns: [app-log-*], template: { settings: { number_of_shards: 3, number_of_replicas: 1, index.lifecycle.name: app-log-policy, index.lifecycle.rollover_alias: app-log-write } } }如果使用 ILM 的 Rollover寫入側應使用別名app-log-write查詢則使用app-log-*。日志保留周期的選擇要結合業務需求ERROR 日志可以保留更久普通 INFO 日志保留 7 到 15 天通常就夠。注意不要只設置 ILM 而忽略磁盤容量評估。保留 30 天日志至少要把每天日志量乘以 30 乘以副本數再算上 ES 索引膨脹和 overhead才能確認集群容量是否夠用。6. 排障實戰從一條報警到根因定位的完整鏈路日志體系設計得再好最終還是要回歸到排障場景。用一個常見例子說明凌晨收到告警訂單服務 ERROR 增多接口 P99 升高。這時候應該怎么查。6.1 先用時間和級別縮小范圍不要盲目搜全文排障第一步不是搜具體異常棧而是確定影響范圍。在 Kibana 中使用時間范圍過濾最近 15 分鐘再疊加服務名和級別。service:order-service AND level:ERROR AND timestamp now-15m如果日志量仍然很大可以加上uri或status進一步縮小范圍。比如只查看POST /api/order的錯誤日志。service:order-service AND level:ERROR AND uri:/api/order AND timestamp now-15m排序按timestamp升序先看最早的異常因為第一個異常往往是后續大量錯誤的源頭。如果看到Connection timed out或Read timed out要意識到這可能是下游依賴導致的連鎖反應先找出被調用方是否也有異常。6.2 用 TraceID 串聯完整調用鏈確定一條典型錯誤日志后復制其中的traceId在 Kibana 中搜索。traceId:8f3a1b2c3d4e5f6a7b8c搜索時不限制服務名。只要 TraceID 在所有服務間透傳正確就能查到這個請求經過的所有服務、所有實例的日志。按時間順序排列后可以看到請求從網關進入訂單服務然后調用支付服務最后在哪里耗時最長。日志中會看到類似這樣的關鍵點訂單服務日志顯示調用支付服務開始和結束。支付服務日志顯示處理耗時超過 3 秒。支付服務之后出現數據庫超時或連接池等待。這一步的核心是確認異常發生位置而不是只看最外層報錯。外層的RestClientException可能只是下游超時的表象根因在支付服務的數據庫連接或 SQL 執行上。6.3 從異常日志特征定位根因類型不同錯誤特征對應不同排查方向整理成速查表會很有用。日志特征可能根因下一步檢查status500 大量異常棧服務內部異常看異常棧、線程池、連接池Connection timed out網絡不通或連接池耗盡檢查目標服務、端口、連接池配置Read timed out下游處理慢查看下游服務耗時、GC、慢 SQLlock wait timeout exceeded數據庫鎖競爭查數據庫事務、慢 SQL、死鎖日志OutOfMemoryError內存不足或泄漏查看對堆配置、GC 日志和