日誌格式化最佳實務:JSON、事件時間與關聯 ID
了解如何以單行 JSON 輸出事件,統一時間、級別和欄位型別,關聯請求與追蹤,並限制敏感欄位輸出。
假設 UTC 03:14 有一筆付款請求逾時。閘道記下路由和以毫秒表示的回應時間,付款服務卻只寫了「上游逾時」,把堆疊追蹤分成好幾行。兩邊的日誌都送到了儲存端,但只有一邊能用路由篩選,堆疊被拆成多筆事件,兩筆紀錄也沒有共同的識別碼。
日誌格式定義一筆事件如何編碼,以及查詢時能依賴哪些欄位。 即使各服務都輸出 JSON,只要一邊把 duration_ms 記為數值,另一邊輸出 "900ms" 字串,就很難套用相同條件做彙總。
先決定一筆事件到哪裡結束
自由文字適合開發時逐一查看程序輸出。半結構化日誌會加上固定前綴或鍵值,結構化事件則約定欄位和資料型別。同一個逾時事件,用不同格式輸出,採集端需要做的事也不同。
| 格式 | 範例 | 採集時需要處理的事 |
|---|---|---|
| 自由文字 | Upstream timed out after 900 ms |
從訊息擷取耗時和單位 |
| 半結構化 | level=ERROR duration_ms=900 msg="Upstream timed out" |
依鍵值語法和引號規則解析 |
| 結構化 | {"level":"error","duration_ms":900,"message":"Upstream timed out"} |
解析 JSON,再套用約定的欄位格式 |
若檔案或標準輸出是逐行收集,讓 JSON 編碼器每行寫一個物件。訊息裡的引號、反斜線和換行交給編碼器跳脫。若要直接傳送排版後的多行 JSON,需另訂事件邊界。開發環境的主控台可以使用便於閱讀的樣式,正式環境仍用 JSON 保留相同欄位。JSON 字串與跳脫規則
Go 的 slog.JSONHandler 會逐行輸出 JSON。Nginx 要先在 log_format 定義 JSON 物件,再用 escape=json 跳脫變數的值,並在 access_log 選用該格式。PostgreSQL 15 以上設定 log_destination = 'jsonlog' 時,還要啟用 logging_collector。各來源輸出的欄位不同,先看實際紀錄,再決定怎麼對應到共用欄位。Go slog · Nginx 日誌模組 · PostgreSQL 日誌設定
統一嚴重程度與事件時間
先定義查詢使用的級別,例如 debug、info、warning 和 error,再把各來源的值對應過去。代表相同意思的 WARN 和 warning 應能用同一個條件查到。各函式庫的整數級別可能不同。OpenTelemetry 的 SeverityNumber 有自己的級別範圍,和字串 SeverityText 是不同欄位。OpenTelemetry 日誌資料模型
排查逾時要看事件發生時間。RFC 3339 應帶 Z 或明確的 UTC 偏移,Unix 時間戳則要約定用秒、毫秒或奈秒。若能取得觀測或寫入時間,就另外保存。即使紀錄晚了 30 秒才送達,也應能按原本發生的時間範圍查到。統一用 UTC 能減少時區換算,主機時鐘偏差仍要另外處理。RFC 3339
保留能縮小查詢範圍的欄位
每筆事件都應能對應到服務和環境。要區分多個執行個體時,可以加上執行個體識別碼。版本或提交識別碼可寫進事件,也可以附在收集後仍查得到的資源屬性。新舊版同時處理流量時,就能檢查逾時是否集中在其中一個版本。檔名、函式與行號可由日誌元件在需要的路徑上附加。
路由使用 /orders/{order_id} 這類範本,耗時使用數值欄位 duration_ms。各服務要沿用相同的名稱、資料型別和單位。訂單編號或 HTTP 標頭名稱不適合拿來動態產生欄位。識別碼放在固定欄位的值裡,並事先確認缺欄或型別變更會如何影響解析。
區分請求識別碼與追蹤識別碼
應用程式的 request_id 能找出沿途使用同一個值的紀錄。Trace ID 指向整條分散式追蹤,Span ID 指向其中一次操作。有作用中的 Span 時,從監測函式庫讀取目前的識別碼寫入日誌,並把追蹤上下文往下一個服務傳。沒有作用中 Span 的路徑仍可記錄請求識別碼。查詢結果只包含已送達且仍在保留期限內的事件,對應追蹤也可能因取樣或保留政策而查不到。W3C Trace Context
以下是單行 JSON 的合成事件。堆疊中的換行經過跳脫,仍保留在同一筆事件裡。
{"time":"2026-11-09T03:14:00Z","level":"error","service":"payments","env":"prod","version":"v2.3.1","route":"/orders/{order_id}","duration_ms":900,"request_id":"req-example-42","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","message":"Upstream returned \"timeout\"","error_type":"UpstreamTimeout","stack_trace":"UpstreamTimeout\n at capture (payments.go:71)"}
呼叫路徑對排查有幫助時,再替例外附上堆疊。報價到期等預期中的業務拒絕,通常只需錯誤碼和必要資訊。若要按檔案或函式彙總,可把堆疊框架拆成欄位。舊元件若以純文字分行輸出堆疊,就讓收集器辨識每筆事件的首行,並確認後續的堆疊行會合併到原本的錯誤事件。DataKit 多行日誌收集(簡體中文)
決定哪些欄位可以離開程序
記錄物件前先列出允許輸出的欄位。保留可控制的錯誤類型與排查需要的識別碼,避免序列化整個使用者物件、請求本文或標頭清單。在 Go 中可以實作 slog.LogValuer,決定該物件值透過此途徑記錄時的樣子。也要檢查序列化結果,因為其他格式化途徑、原始訊息和堆疊仍可能帶有敏感資料。OWASP 日誌指引(英文)
套用到正式環境前,讓同一個解析器讀取正常事件、含引號和換行的例外,以及缺少欄位的紀錄。在觀測雲可用 DataKit 收集檔案,再透過 Pipeline 把應用程式的日誌級別對應到 status。在日誌介面檢查解析後的事件時間和欄位型別,也要查看原始訊息是否殘留敏感值。設定好 APM 和日誌收集後,再把擷取的 trace_id 與實際能查到的追蹤對照。DataKit 日誌收集器(簡體中文) · 觀測雲日誌與追蹤關聯(英文)
格式穩定後,可參考日誌聚合把多個來源集中到共同的儲存端。結構化日誌概念(簡體中文)說明更廣泛的使用方式。
