日誌：一次事故吃掉整月預算，關鍵那筆正好被丟掉

日誌的價值不在「有記錄」，而在「能被查詢」。而這件事完全取決於它有沒有結構。

// ❌ 純文字：人看得懂，機器只能做字串比對
2026-08-13 22:14:07 ERROR Failed to process order 8821 for user 42 after 3 retries

// ✅ 結構化：每個欄位都可以被過濾、聚合、比較
{"ts":"2026-08-13T22:14:07Z","level":"ERROR","msg":"order processing failed",
 "order_id":8821,"user_id":42,"retry_count":3,"duration_ms":4210,
 "service":"order-api","trace_id":"4bf92f...","span_id":"00f067..."}

差別在哪：能問的問題完全不同

• 純文字只能問：「有沒有出現這個字串」。
• 結構化可以問：「重試超過 2 次、耗時超過 3 秒、而且發生在特定使用者身上的請求有哪些」——這正是 ch01 說的「未知的未知」：一個你事前沒想過的維度組合。

訊息本身要固定，變數放欄位

這是很多人做一半的地方：明明用了 JSON，卻把變數塞進 msg 裡。

// ❌ msg 每一筆都不一樣，無法聚合「這類錯誤發生幾次」
"msg": "Failed to process order 8821 for user 42"

// ✅ msg 是固定的分類，變數獨立成欄位
"msg": "order processing failed", "order_id": 8821, "user_id": 42

這與 ch02 的「錯誤訊息不要當 metric label」是同一個原則的兩面：會變動的值是資料，不是分類。差別只在於——在日誌裡它們是欄位（成本是加法），在 metrics 裡它們是 label（成本是乘法）。

Java／Spring 的做法

// logback-spring.xml 用 JSON encoder（logstash-logback-encoder）
<encoder class="net.logstash.logback.encoder.LogstashEncoder"/>

// 程式碼用結構化參數，不要自己拼字串
log.atError()
   .setMessage("order processing failed")
   .addKeyValue("order_id", orderId)
   .addKeyValue("retry_count", retries)
   .log();

// ❌ 不要這樣：變數進了訊息本體
log.error("Failed to process order " + orderId);

日誌等級是最被濫用的機制。大部分專案的 WARN 裡塞滿了沒有人會處理的東西，而 ERROR 裡混著使用者輸入錯誤。結果是等級失去了篩選能力——而那本來是它唯一的用途。

用「誰要做什麼」來定義

一個實用的檢查

對每一行 log.error(...) 問：「如果這行在半夜出現一百次，我需要有人起床嗎？」答案是否，那它就不是 ERROR。

不要用日誌數量當指標

「用日誌計算錯誤率」是很常見的做法，但它的成本結構很差：你為了得到一個數字，付了完整的日誌儲存與索引費用。

堆疊追蹤要克制

一個 Java 堆疊追蹤動輒 2~5 KB，而且深層框架的堆疊有 80% 是重複的。

• 同一個錯誤重複發生時，不要每次都印完整堆疊（下面的去重那節會處理）。
• 預期內的例外不要印堆疊：驗證失敗、找不到資料——它們的堆疊沒有資訊量。
• Logback 可以設定堆疊的最大深度與過濾框架的 package。

ch01 說三本柱之間需要橋，而 trace_id 是其中最便宜、也最不能省的一座。

它解決的問題

一個請求穿過五個服務，每個服務都寫了日誌。沒有 trace_id 時，你只能靠時間戳前後推測——而在每秒幾百個請求的系統裡，那是不可能的。

-- 有 trace_id：一句查詢就撈出這一次請求的完整故事
{trace_id="4bf92f3577b34da6a3ce929d0e0e4736"}

gateway    → 收到請求
order-api  → 建立訂單
payment    → 呼叫外部支付（重試 3 次）
payment    → 逾時失敗
order-api  → 回滾，回傳 500

Java／Spring 怎麼做

核心機制是 MDC（Mapped Diagnostic Context）——一個綁在執行緒上的鍵值表，logger 輸出時會自動帶上。

// Spring Boot 3 + Micrometer Tracing：trace_id 會自動放進 MDC
// logback pattern 直接引用即可
<pattern>%d %-5level [%X{traceId},%X{spanId}] %logger - %msg%n</pattern>

// JSON encoder 則會自動把整個 MDC 展開成欄位

除了 trace_id，還有三個欄位值得每筆都帶

• service／env／version：與 metrics 和 trace 用同一套命名（ch01 說的「統一標籤語彙」），否則無法自動關聯。
• tenant_id／customer_id：多租戶系統裡，「只有某個客戶出問題」是極常見的模式。
• 請求的關鍵識別碼（order_id 之類）：注意這是欄位不是 metric label——在這裡它的成本是加法，完全合理。

由此得到的排查動線

① Grafana 看到 p99 尖峰（metrics，ch03）
② 點 exemplar 跳到一條代表性的 trace（ch05）
③ 複製那條 trace 的 trace_id
④ 到日誌系統用 trace_id 查 → 看到完整的細節與例外堆疊

這條動線能不能一路走通，比每一樣工具各自做得多好都重要。而它成立的唯一前提，就是每筆日誌都有 trace_id。

日誌平台的帳單通常拆成三塊，而它們的成長方式不同。搞清楚自己付的是哪一塊，才知道該砍什麼。

• Ingest（寫入）：與「筆數 × 每筆大小」成正比。這通常是最大的一塊，也是最容易失控的。
• 索引：與「要能被搜尋的欄位量」成正比。這是 ELK 與 Loki 分道揚鑣的地方。
• 儲存：與「保留期」成正比。相對便宜，但它是唯一會持續累積的。

兩種索引策略

分層保留

不是所有日誌都值得留一樣久：

ERROR / 稽核紀錄     → 90 天以上（可能有合規要求）
WARN / INFO         → 14~30 天
DEBUG / 存取日誌     → 3~7 天，或直接取樣

熱儲存（可查詢） 7 天 → 冷儲存（物件儲存，需要時再撈） 1 年

一個最容易忽略的成本：同步寫入

<appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
  <queueSize>8192</queueSize>
  <discardingThreshold>0</discardingThreshold>  <!-- 佇列滿時不要偷偷丟掉 WARN 以下 -->
  <neverBlock>true</neverBlock>                  <!-- 佇列滿時丟棄而不是阻塞請求 -->
</appender>

日誌治理的目標不是「少記一點」，而是「在故障時仍然記得住重要的東西」。有三種手段，效果與風險各不相同。

① 分級取樣：成功取樣，失敗全留

成功的請求存取日誌  → 取樣 1%（統計上足夠）
慢請求（> SLO 門檻） → 100% 保留
所有 WARN 以上      → 100% 保留

這是投報比最高的一種：存取日誌通常佔總量的八成以上，而其中 99% 是「一切正常」。

② 去重／聚合：同一個錯誤不要記一千次

ERROR order processing failed（含完整堆疊）
... 之後 60 秒內
WARN  order processing failed × 12,847（省略重複堆疊）

③ 動態調整等級

正式環境預設 INFO，但排查時需要 DEBUG。重新部署來改 log level 是最糟的做法（改變了現場，而且可能讓問題消失）。

// Spring Boot Actuator：不重啟就能改單一 logger 的等級
POST /actuator/loggers/com.shop.payment
{"configuredLevel": "DEBUG"}

用完記得改回去——忘記關掉的 DEBUG 是日誌帳單暴增最常見的原因之一。

不該記的東西（這一節是合規問題）

一個實用的防線

在序列化層統一遮蔽：對敏感欄位加註解（例如自訂 @Masked），由 JSON encoder 自動替換成 ***。比要求每個工程師記得不要記，可靠得多。

徵狀

週日凌晨兩點，日誌平台開始大量丟棄資料。而值班工程師發現這件事，是因為他查不到另一個服務的日誌——那個服務跟這次事故毫無關係。

• 平常全公司日誌約 2 GB/天，這六小時內產生了 900 GB。
• 平台觸發 ingest 限流，開始無差別丟棄。
• 當天的日誌成本超過整個月的預算。
• 最糟的是：真正該被保留的、其他服務的關鍵日誌，被那 900 GB 擠掉了。

診斷

-- 依服務看日誌量（大部分平台都有這種內建指標）
sum by (service) (rate(log_bytes_total[5m]))
-- payment-worker: 41 MB/s   ← 其他服務加起來不到 0.1 MB/s

撈幾筆出來看，全部是同一則錯誤：

{"level":"ERROR","msg":"Failed to call risk service",
 "request_body":"{...完整的 8KB 請求內容...}",
 "stack_trace":"...約 4KB..."}

根因（四件事相乘）

正常：  1,000 req/s × 300 B  = 0.3 MB/s
故障中：1,000 × 10 次 × 12 KB ≈ 120 MB/s   ← 400 倍

而真正的傷害是連帶的

平台的限流是全域、無差別的。於是這一個服務的失控，讓所有服務的日誌一起被丟——包括那些正在排查其他問題的團隊。可觀測性系統本身變成了單點故障。

修法

教訓

把前面收成一份可以直接執行的清單。這六件事決定了你的日誌是資產還是負債。

什麼時候不要用日誌

• 要計數／算比率 → 用 metrics（ch02）。用日誌算錯誤率是付完整儲存費換一個數字。
• 要看一次請求的時間分佈 → 用 trace（ch05）。從日誌的時間戳推算跨服務耗時是徒勞。
• 要長期趨勢 → 用 metrics。日誌的保留期通常遠短於你需要的趨勢範圍。

一個判斷每一行 log 的問題

寫下 log.info(...) 之前問三件事：

① 誰會讀它？（如果答案是「沒有人」，那就不要寫）
② 在什麼情境下讀？（排查什麼問題）
③ 讀的時候需要哪些欄位？（那些就是該加的 key-value）

答不出第一題的日誌，是純粹的成本。而它們通常佔了總量的大半。

四個盲點

• 它看不到「沒有執行到的程式碼」。if 分支沒進去、事件沒被觸發、排程沒被排——日誌裡什麼都沒有，而那正是問題（ch03 的 absent_over_time 是唯一的補救）。
• 它看不到聚合層的問題。每一筆日誌都正常，但「這個請求發了 200 次相同的呼叫」在日誌裡只表現成 200 筆正常紀錄——這與 db ch08 的 N+1 是同一個盲點。
• 它的時間戳不可靠。跨機器的時鐘會有偏差，非同步 appender 會讓寫入順序與發生順序不一致。不要用日誌的時間戳去推算跨服務的耗時——那是 trace 的工作。
• 被丟掉的日誌不會留下痕跡。取樣、限流、佇列溢出——這些都是靜默的。「查不到」不等於「沒發生」，而多數人會把前者當成後者。

三筆容易低估的帳

• 同步寫入拖慢請求：日誌後端塞住時，它會反壓到你的請求執行緒。而 neverBlock=true 的代價是靜默丟棄。
• 索引成本可能超過原始資料：全文索引尤其明顯。這是「先想清楚哪些欄位真的需要被搜尋」的理由。
• 合規風險：一旦寫出去就散佈到收集器、索引、備份、冷儲存。這是唯一一種「事後無法補救」的日誌問題。

把這一章收成三句

下一章處理三本柱的最後一根：trace 是唯一能回答「這一次的時間花在哪」的東西，而它最常見的失敗，是在你最需要的那一段斷掉。