ログフレームワークの選び方:出力から収集までの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 クイックスタート(英語)

ログレベルの基礎

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ