ログフレームワークの選び方:出力から収集までの8項目
ログフレームワークを、出力形式、コンテキスト、例外、バックプレッシャー、サンプリングなど8項目で比較し、収集側で同じログを確認します。
ロガーを更新したあと、決済サービスのアラートが急に鳴らなくなった。エラーログは出ていても、検索条件が ERROR を見ているのに、新しい出力ではレベルが数値かもしれない。あるいはアプリケーションがスタックトレースを複数行で書き、収集側が各行を別々のイベントとして保存している。ロガーが設計どおりに動いていても、アプリケーションからアラートまでの途中で情報が失われる。
ログフレームワークはその経路全体を見て選びたい。正常なリクエスト、例外を伴う失敗、ログが集中する時間帯を用意する。同じサンプルを使えば、API から運用まで八つの観点を比べられる。
アプリケーションから何が出るか
1. レベルとフィルタリング
レベルをどの値で出し、どこで絞り込むかを確認する。数値のログレベル、ERROR のような文字列、HTTP ステータスコードは役割が違う。調査に必要なレコードを条件で選べるかを見ておく。無効なレベルでも、呼び出し前に重い引数を作っていれば、その処理コストは残る。 Go slog のドキュメント(英語)
2. 構造化出力
収集側が読める形式を選ぶ。一行に一つの JSON オブジェクトを書けば、フィールドの型を保って一行ずつ解析できる。開発中は読みやすい形式でもよい。イベント時刻、レベル、調査に使うフィールドの名前と型を決め、実際の出力を見比べる。数値が文字列に変わるだけで範囲検索の結果は変わり得る。
3. コンテキストの伝播
プロセス全体の属性と、リクエストや一件のイベントに属する情報を分ける。子ロガーやアダプターでサービス名などを持たせる場合は、バックグラウンド処理に引き継がれ、別のリクエストには残らないか確認する。トレースコンテキストがあるときは実際の trace ID を記録する。Guance のトレース詳細は、トレース全体の関連ログを trace_id で探し、インデックスのマッピングに service、env、version などを使う。対応するログの収集とアクセス権限も必要になる。 Guance のトレース詳細
4. 例外の記録
フレームワークがサポートする方法で例外オブジェクトを渡し、型、メッセージ、スタックなど必要な情報が出るか確認する。改行をエスケープしたスタックは一行の JSON に収まる。テキストのスタックが複数行に分かれる場合は、収集側で複数行をまとめる設定を使い、イベントの区切りを確かめる。 DataKit のログ収集
負荷がかかったときの挙動
5. 書き込みコストとバックプレッシャー
同じイベントを本番に近い頻度と出力先で測る。出力を捨てる sink でエンコードコストを切り分け、実際のファイルやストリームで書き込み待ちを見る。非同期キューに移せる処理はあるが、満杯時の挙動は設定次第だ。待つ、捨てる、同期で処理するなどの違いが、メモリーや応答時間、欠落件数にどう現れるかを確認する。終了時にキューを排出できるかも見る。 Log4j 2 の非同期ログ(英語) · Python QueueHandler(英語)
6. サンプリングとフィルタリング
どの記録をどの段階で減らせるかを決める。サンプリングはストリームの一部を残す方法で、フィルターは条件に合うレコードを選ぶ。必要なエラーや監査ログは任意のサンプリングの対象から外し、残ったデータでアラートが機能するか確かめる。元の件数を推定するにはサンプリング方式も把握しておく。
7. アプリケーションとテストへの影響
出力先が遅い場合、接続できない場合、フィールドをエンコードできない場合の動きを試す。一部のロガーでは Fatal の呼び出しでプロセスが終了する。通常のエラー呼び出しを置き換える前に API の挙動を確かめる。テストではメモリー上の sink を使うと、出力と失敗時の挙動を確認しやすい。
チームが維持できるものを選ぶ
8. ランタイムと周辺環境
実際に使うランタイム、依存バージョン、リリースとセキュリティ更新の履歴、フレームワークとの連携を確認する。Java では実行時の SLF4J プロバイダー、PHP では PSR-3 パッケージのバージョンを見る。チームが仕組みを把握している出力経路なら、トラブル時にも切り分けやすい。
| ランタイム | 出発点になる選択肢 | 確認するところ |
|---|---|---|
| Node.js | Pino の JSON 出力 | 子ロガーのフィールド、destination や transport |
| Go | Go 1.21 以降の slog、または Zap、Zerolog | Handler や Writer、フィールド名、実負荷のコスト |
| Java | SLF4J と互換性のある Logback や Log4j 2 プロバイダー | 実際に読み込むプロバイダーとアペンダー |
| Python | 標準の logging とフォーマッター、ハンドラー。あるいは structlog や Loguru | 整形の場所、コンテキストの伝播、キューの排出 |
| PHP | PSR-3 の背後で使う Monolog | 実際のハンドラー、フォーマッター、出力先 |
| Ruby | 単一出力には Logger、構造化ペイロードや複数アペンダーには Semantic Logger | 書式、キューが満杯のときの方針、フラッシュ |
収集側で同じログを確かめる
ローカルの Python 3.13.1 で、決済エラーを独自フォーマッターから一行の JSON に出した。level は文字列の ERROR、http_status_code は数値の 503 で、例外の改行はエスケープされている。別のテストでは、容量一件でコンシューマーのいないキューに QueueHandler をつないだ。一件目は残り、二件目はハンドラーのエラー処理に進んだ。ここで確認したのは出力形式とキューが満杯になったときの挙動だ。
実際のサービスでは、設定済みのコンテナストリームやファイルを DataKit で収集する。正常行とエラー行を Guance Pipeline に通し、イベント時刻、status へのレベル変換、HTTP コードが数値のまま独立していることを確認する。ネットワーク経由なら送受信のプロトコルとエンコードを合わせ、再試行やバッファーも見る。切り替える前に、テスト用ソースで既存のアラート条件を試す。 Guance Pipeline クイックスタート(英語)
