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(簡體中文)

Ruby 日誌基礎(英文) · Rails 日誌(英文) · Semantic Logger 實作(英文)

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

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

立即開始

选择观测云版本

代码托管平台