如何選擇日誌框架?從應用程式到採集器的八個檢查項目

從輸出格式、上下文、例外、背壓、取樣等八個面向比較日誌框架,並在採集端驗證同一批樣本。

最佳實務
多條軌道穿過同一個構造的插畫

換了日誌函式庫,結帳服務的告警突然安靜下來。錯誤日誌還有寫,只是原本的查詢篩選 ERROR,新輸出卻用數值表示級別。也可能是應用程式把堆疊寫成多行,採集器把每一行當成一筆。函式庫照預期執行,從應用程式到告警的路徑仍可能出問題。

選日誌框架時,先拿正常請求、帶例外的失敗請求與一段尖峰日誌,沿著整條路徑比較。用同一批樣本核對八個面向,從程式怎麼呼叫,一直看到團隊能否維護。

應用程式會寫出什麼?

1. 級別與篩選

確認框架如何表示級別,以及在哪一層過濾。數值級別、ERROR 這樣的字串和 HTTP 狀態碼各有用途。要確定既有查詢能選出團隊需要的記錄。若昂貴的引數在呼叫前就求值,即使該級別已關閉,應用程式仍須負擔計算成本。 Go slog 文件(英文)

2. 結構化輸出

選採集器讀得懂的格式。每行一個 JSON 物件,可保留欄位型別,也方便逐行解析。開發環境可以使用易讀的輸出。先約定事件時間、級別與診斷欄位的名稱和型別,再看實際寫出了什麼。耗時若從數值變成字串,範圍查詢可能得到不同結果。

3. 上下文傳遞

分開處理程序層的屬性、請求欄位與單筆事件欄位。子 Logger 或上下文轉接器可以帶上服務或請求識別,但要檢查這些欄位是否跟得到背景工作,以及不同請求之間是否會串用。有追蹤上下文時再寫入實際的 trace ID。觀測雲的整條追蹤以 trace_id 找相關日誌,索引映射可用到 service、env、version。相關日誌仍須已採集且具備存取權限。 觀測雲追蹤詳情(簡體中文)

4. 例外記錄

用框架提供的介面傳入例外物件,確認輸出包含需要的類型、訊息和堆疊。轉義換行後,堆疊可以留在一行 JSON 裡。文字堆疊若佔多行,再設定採集器的多行合併規則,並檢查每筆事件的邊界。 DataKit 日誌採集(簡體中文)

負載上來後會怎麼樣?

5. 寫入成本與背壓

用相同事件、接近實際的頻率和正式目的地做比較。丟棄輸出的 sink 可單獨量測編碼成本,實際檔案或串流才看得到寫入延遲。非同步佇列能把部分工作移出請求執行緒。佇列滿了以後,可能阻塞、丟棄或改為同步處理,取決於設定。也要檢查記憶體、請求延遲、丟失量與關閉時的清空行為。 Log4j 2 非同步日誌(英文) · Python QueueHandler(英文)

6. 取樣與過濾

先決定哪些記錄能減量,以及在哪一層做。取樣保留串流的一部分,過濾則按條件保留或丟棄。必要的錯誤與稽核記錄應排除在可選的取樣規則之外,並檢查其餘資料能否繼續支援告警。若要從取樣後的筆數估計總量,還需要知道取樣方式。

7. 對應用與測試的影響

測試目的地變慢、寫不進去,以及欄位無法編碼時的反應。部分 Logger 的 Fatal 方法會結束程序,不能把它直接當成一般錯誤呼叫替換。測試可用記憶體 sink 核對輸出和失敗行為,再比較日誌啟用、停用和積壓時的應用狀態。

團隊要維護哪些東西?

8. 執行環境與生態

確認實際使用的執行環境版本、相依套件、發行和安全更新紀錄,以及框架如何整合。Java 要確認執行時啟用哪個 SLF4J provider,PHP 要核對 PSR-3 套件版本。輸出路徑清楚、團隊熟悉的函式庫,維護時通常更容易定位問題。

執行環境 可以從哪裡開始 要核對的範圍
Node.js Pino 的 JSON 輸出 子 Logger 欄位與選用的 destination 或 transport
Go Go 1.21+ 的 slog,或 Zap、Zerolog Handler、Writer、欄位名稱與實際負載成本
Java SLF4J 搭配相容的 Logback 或 Log4j 2 provider 執行時啟用的 provider 與 appender
Python 標準庫 logging 搭配 formatter 和 handler,或 structlog、Loguru 格式化位置、上下文傳遞和佇列的清空行為
PHP PSR-3 介面後的 Monolog 實際 handler、formatter 與輸出目的地
Ruby 單一輸出可用 Logger,多 appender 與結構化 payload 可評估 Semantic Logger 輸出格式、佇列策略與 flush 行為

到採集端核對同一筆記錄

本機用 Python 3.13.1 和自訂 formatter 輸出一筆合成結帳錯誤。整筆是一行 JSON,level 保留字串 ERROR,http_status_code 保留數值 503,例外訊息與堆疊以轉義換行保存。另一個測試將 QueueHandler 接到容量為一且沒有消費者的佇列。第一筆保留,第二筆進入 handler 的錯誤處理。這組樣本用來核對輸出形狀與佇列滿載行為。

對實際服務,先由 DataKit 採集已配置的容器串流或檔案,把正常和錯誤樣本放到觀測雲 Pipeline 驗證。確認事件時間、級別映射到 status,HTTP 狀態碼則留在自己的數值欄位。若走網路,檢查發送端與接收端的協定、編碼、重試和緩衝。切換前在測試來源重跑既有告警查詢。 觀測雲 Pipeline 快速入門(簡體中文)

認識日誌級別

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

在线开通,按量计费,真正的云服务!

立即開始

选择观测云版本

代码托管平台