Ruby 日誌函式庫怎麼選?比較 Logger、Lograge 等六種方案
比較六種 Ruby 日誌函式庫,選擇 Rails 請求格式與慢速寫入策略,並驗證採集器收到的最終日誌。
結帳請求回傳 503。Rails 請求摘要記下回應狀態,應用程式的錯誤日誌則交代哪個上游呼叫逾時。這兩筆資料可以放在同一個日誌檢視器裡,欄位卻各有用途。選 Ruby 日誌函式庫時,先想清楚誰會寫出哪一筆,以及採集器最後會讀到什麼。
單一輸出的指令稿或服務,可以從 Ruby 的 Logger 開始。Rails 專案則可以先處理請求日誌的格式,再決定要不要換掉應用程式的 Logger。需要結構化 payload、多個目的地或慢速寫入策略時,再評估其他實作。
六種 Ruby 日誌方案怎麼選?
| 方案 | 常見用途 | 選用時要確認 |
|---|---|---|
| Ruby Logger | 同步寫入單一 IO 或檔案,可設級別與 formatter | 預設是文字。JSON 和檔案輪替須分別設定 |
| Lograge | 整理 Rails 的請求摘要 | 預設是鍵值對,JSON 需明確設定,最後一行仍由輸出 Logger 決定 |
| Semantic Logger | 結構化 payload、多個 appender,預設以背景執行緒寫入 | 確認佇列與慢速目的地的處理策略。5.2.0 需要 Ruby 3.2 以上 |
| Log4r | 使用階層式 logger 和具名 outputter 的既有程式 | 查得最近的 RubyGems 版本是 2012 年的 1.1.10。核對 Ruby 版本與現有設定 |
| Logging | 使用多個 appender 與自訂 layout 的既有程式 | 留意 JSON layout 和緩衝行為。查得最近版本是 2024 年的 2.4.0 |
| Ougai | 提供結構化欄位的 Logger 子類別,預設 Bunyan JSON |
級別數值、時間格式和例外欄位取決於 formatter。2.1.0 需要 Ruby 3.1 以上 |
Ruby 標準庫提供 Logger,也會把它獨立發行為 gem。檔案輸出在寫入時有同步保護,可依大小或週期設定輪替。想少寫一些 JSON formatter 程式碼,可以評估 Ougai。它可傳入結構化欄位,也有 before_log hook。Bunyan formatter 的 level 是數值,時間是字串。Pino formatter 則使用 Unix 毫秒,例外的欄位結構也不同。選用時記得核對現有解析規則。 Ougai 的 formatter(英文)
先確認誰寫 Rails 請求摘要
Lograge 將訂閱到的 Rails 事件整理成摘要。控制器事件通常包含方法、路徑、狀態碼與耗時,資料裡有資料庫或檢視處理時間時才會加入。付款失敗這類業務事件仍由應用程式另外寫入。Lograge 0.15.1 預設使用 Lograge::Formatters::KeyValue,未更改設定時以 info 將格式化後的訊息交給 Logger。需要 JSON 訊息時選 Lograge::Formatters::Json,並確認接手的 Logger 怎麼輸出。 Lograge 設定(英文)
Lograge 和應用程式可能共用一個輸出。如果 Rails 已經透過 rails_semantic_logger 等整合寫請求日誌,啟用 Lograge 後要實際看一次請求。兩個訂閱器寫出同一份摘要可能讓 HTTP 失敗次數膨脹。同一個失敗請求另外留下一筆業務錯誤,則能補充排查線索。請求狀態碼和日誌級別應使用不同欄位。 Semantic Logger 的 Rails 整合(英文)
決定目的地變慢時怎麼處理
Semantic Logger 可把同一筆事件送往多個 appender。佇列還有空間時,實際寫入由背景執行緒處理。5.2.0 的預設主佇列上限為 10,000 筆,滿載時預設會讓呼叫方等待。有界佇列若改成非阻塞模式,滿載時會丟棄新事件。寫入檔案和遠端目的地若共用路徑,要用最慢的 appender 測試佇列深度和丟棄數量。 Semantic Logger 維運文件(英文)
程式正常結束時會嘗試 flush,也可明確呼叫 SemanticLogger.flush,讓已設定的 appender 處理佇列裡的事件。程序異常結束仍可能遺失記憶體內的資料,flush 成功也不代表下游已持久化。若有稽核要求,要另外定義可靠投遞與失敗處理方式。若要替換 Log4r 或 Logging,可以先盤點 outputter、appender 和格式,再決定新函式庫需要保留哪些行為。
看採集器實際讀到哪一行
本機測試用 Ruby 2.6.10 執行 Logger 1.7.0,並直接呼叫 Lograge 0.15.1 的 formatter 處理一筆合成請求。輸出有這些差異。
| 輸出階段 | 實際看到的欄位 |
|---|---|
| Lograge 鍵值 formatter | method=GET path=/checkout status=503 duration=42.50 |
| Lograge JSON formatter | JSON 物件中的數值 status: 503 和 duration: 42.5 |
把同一段 JSON 交給預設 Ruby Logger 的 info |
先有含 INFO 的文字前綴,再有 JSON 訊息 |
| Ruby Logger 的自訂 JSON formatter 輸出業務錯誤 | level: "ERROR"、message: "upstream timeout" 和 ISO 8601 time |
若解析器預期整行都是 JSON,預設 Logger 的文字前綴就會使解析失敗。結構化的外層 Logger 也可能把內層 JSON 寫成訊息字串。換庫時要看最終輸出。本機測試涵蓋 formatter 與外層包裝,範圍限於輸出形狀。
DataKit 可以採集已設定的容器 stdout 或檔案。在觀測雲 Pipeline 試解析最終的請求和業務日誌,檢查事件時間、級別、payload 與狀態碼的型別。將請求的 503 保留在 http_status_code 等獨立欄位,ERROR 或數值級別則映射到日誌監控使用的級別欄位。完成後再用相同的請求與錯誤篩選條件查測試來源。 DataKit 日誌採集(簡體中文) · 觀測雲 Pipeline(簡體中文)
