Ruby のログライブラリ 6 選を比較:Logger・Lograge・Semantic Logger ほか
Ruby のログライブラリを 6 種類比較。Rails のリクエストログ、遅い書き込みへの対処、収集側に届くログの形式を確認します。
決済リクエストが 503 を返した。Rails のリクエストログには応答のステータスが残り、アプリケーションのエラーログにはどの上流呼び出しがタイムアウトしたかが残る。同じログ画面に並べて見るとしても、フィールドの役割は違う。Ruby のログライブラリを選ぶときは、まずどのロガーが何を記録し、収集側にどんな一行が届くかを整理したい。
出力先が一つのスクリプトやサービスなら、Ruby の Logger から始めやすい。Rails では、アプリケーション全体のロガーを替える前に、リクエストログに専用のフォーマッターが必要かを考える。構造化ペイロード、複数の出力先、書き込みが遅くなったときの方針が必要なら、候補が変わる。
Ruby のログライブラリ 6 種類を比べる
| ライブラリ | 向いている用途 | 確認すること |
|---|---|---|
| Ruby Logger | 一つの IO やファイルへの同期書き込み。レベルとフォーマッターを設定できる | 既定はテキスト。JSON 化とファイルのローテーションは別々に設定する |
| Lograge | Rails のリクエストを短いサマリーにまとめる | 既定はキー・値形式。JSON は明示して選び、最終出力は書き込み側のロガーで確認する |
| Semantic Logger | 構造化ペイロードと複数のアペンダー。既定ではバックグラウンドで書き込む | キューと遅い出力先の扱いを決める。5.2.0 は Ruby 3.2 以降が必要 |
| Log4r | 階層ロガーや名前付き outputter を使う既存コード | 確認できた最新の RubyGems 版は 2012 年の 1.1.10。実際の Ruby と設定で互換性を確認する |
| Logging | 複数のアペンダーとレイアウトを使う既存コード | 移行時は JSON レイアウトとバッファーの挙動を確認する。最新の公開版は 2024 年の 2.4.0 |
| Ougai | 構造化フィールドを扱う Logger のサブクラス。既定は Bunyan JSON |
レベル、時刻、例外の形式はフォーマッター次第。2.1.0 は Ruby 3.1 以降が必要 |
Logger は Ruby 標準ライブラリに含まれ、gem としても配布される。ファイルへの書き込みは同期され、サイズや期間を指定してローテーションできる。JSON の整形コードを減らしたいなら Ougai が候補になる。構造化フィールドを渡せるほか、before_log フックもある。Bunyan フォーマッターはレベルを数値、時刻を文字列にする。Pino フォーマッターでは時刻は Unix ミリ秒になり、例外の表現も変わる。採用する書式を収集側のパーサーと合わせる。 Ougai のフォーマッター(英語)
Rails のリクエストログを誰が出すか決める
Lograge は購読した Rails イベントを一行のサマリーにまとめる。コントローラーのイベントからメソッド、パス、ステータス、所要時間を取り出し、データベースやビューの処理時間があれば加える。決済が失敗した理由などの業務イベントは、アプリケーションが別に記録する。Lograge 0.15.1 は既定で Lograge::Formatters::KeyValue を使い、整形したメッセージを info でロガーに渡す。JSON を使うなら Lograge::Formatters::Json を選び、受け取ったロガーの出力も確認する。 Lograge の設定(英語)
rails_semantic_logger などがすでにリクエストログを出している場合は、Lograge を有効にしたあと、一件のリクエストで何行出るかを確かめる。同じリクエストサマリーが二つあると失敗件数が膨らむ。一方、リクエストサマリーと決済処理のエラーを一件ずつ残すと、状況を追いやすい。HTTP ステータスとログレベルは別のフィールドにする。 Semantic Logger の Rails 連携(英語)
出力先が遅くなったときの挙動を選ぶ
Semantic Logger は一つのイベントを複数のアペンダーへ送れる。キューに空きがある間、実際の書き込みはバックグラウンドスレッドが引き受ける。5.2.0 の既定のメインキューは最大 10,000 件で、満杯になると呼び出し元が待つ。上限付きキューで非ブロッキングを選ぶと、満杯のときは新しいログを捨てる。ファイルとリモートの出力先を併用するなら、遅い方を含めてキューの深さとドロップ数を見る。 Semantic Logger の運用ガイド(英語)
正常終了時にはキューのフラッシュが試みられ、SemanticLogger.flush も明示的に呼べる。これは残りのログを設定済みのアペンダーへ渡す処理だ。異常終了するとメモリー上のイベントは失われることがあり、フラッシュ後も下流への永続化は別に確認する必要がある。監査向けのイベントには保存と障害時の処理を別途定義する。Log4r や Logging を置き換えるなら、既存の出力先とレイアウトの棚卸しから始める。
収集側に届く一行を確かめる
ローカルで、Lograge 0.15.1 のフォーマッターにテスト用のリクエストを直接渡し、Ruby 2.6.10 上の Logger 1.7.0 でも出力を確認した。
| 出力の段階 | 確認できた内容 |
|---|---|
| Lograge のキー・値フォーマッター | method=GET path=/checkout status=503 duration=42.50 |
| Lograge の JSON フォーマッター | JSON オブジェクトに数値の status: 503 と duration: 42.5 |
同じ JSON を Ruby Logger の既定設定で info に渡す |
INFO を含むテキストの接頭部に JSON メッセージが続く |
| Ruby Logger の独自 JSON フォーマッターで業務エラーを記録 | level: "ERROR"、message: "upstream timeout"、ISO 8601 の time |
一行全体を JSON として読むパーサーは、テキストの接頭部があると解析できない。外側のロガーが構造化されている場合も、内側の JSON がメッセージの文字列に入ることがある。この実行ではフォーマッターとロガーの出力形式を確かめた。
DataKit は設定したコンテナ標準出力やファイルからログを収集できる。Guance Pipeline には最終的なリクエスト行とアプリケーション行を入れ、イベント時刻、ログレベル、ペイロード、HTTP ステータスの型を確認する。リクエストの 503 は http_status_code などに保存し、ERROR や数値のレベルは監視で使う重大度フィールドにマッピングする。そのうえで、テスト用のソースに既存のフィルターを適用して結果を見る。 DataKit のログ収集 · Guance Pipeline(英語)
