ログレベルの使い分け(FATAL から TRACE まで)

処理結果に合わせたログレベルの付け方、終了を伴う API の見分け方、検索やアラートに使う重大度の正規化を解説します。

ベストプラクティス
ログ、メトリクス、トレースを示すイラスト

チェックアウトサービスが在庫 API を呼び出すと、最初の試行がタイムアウトしました。再試行は成功し、購入手続きも完了しました。最初のタイムアウトは記録する価値がありますが、調べたいのが購入手続きの失敗なら、見るべきなのは処理の最終結果です。再試行を使い切って処理を続けられなかったときは、対象のリクエストを追える情報とともに失敗を記録します。

ログレベルは、イベントの重大度や診断情報の細かさを示します。ロガーや出力先は、その値を使ってログを絞り込みます。処理の結果が分かる地点でレベルを決め、ライブラリとコレクターがどう扱うかを確認しましょう。

処理の結果が分かる場所でレベルを付ける

よく使われるレベル チェックアウトサービスでの例
FATAL 必須設定が不正で、サービスを起動できない。
ERROR 再試行後も在庫 API が利用できず、購入手続きが失敗した。
WARN 在庫 API の初回呼び出しがタイムアウトしたが、再試行で処理を完了した。
INFO サービスが起動した、または照合ジョブが完了した。
DEBUG 調査対象を絞って、再試行の判断と所要時間を記録する。
TRACE 対応するフレームワークで、計測を組み込んだ再試行ループの分岐を追う。

この表は、六つの名前を使うチーム向けの運用例です。毎回復旧するタイムアウトが頻発するなら、一件ずつ警告ログを書くよりも、再試行をメトリクスで数えたほうが傾向を把握しやすくなります。失敗したリクエストは、最終結果が分かる層で記録します。各層で ERROR を書くと、利用者に見えた一件の失敗が何件ものエラーログに膨らみます。サービス名、操作名、リクエスト ID やトレース ID を添え、診断に役立つときは例外の詳細も記録します。認証情報やペイロードは診断フィールドに入れません。INFO で確認できるのは、そのイベントが発生したことまでです。サービス全体の状態は、リクエスト経路のほかの部分も見て判断します。

ログを出した後にプロセスが終了するかを確認する

Log4j 2 は、FATAL から TRACE までの六つの通常イベントレベルを定義します。Python 標準の logging は CRITICAL が最上位で、FATAL はその別名です。組み込みの TRACE はありません。Loguru には TRACE と SUCCESS もあります。しきい値やクエリを書く前に、実際に使うライブラリを確認してください。Log4j 2 のレベル · Python のログレベル · Loguru のレベル

FATAL という名前だけでは、呼び出し後にプロセスがどうなるかは分かりません。Python の logging.fatal() は critical() と同じように動作します。Go 標準の log.Fatal() はログを出力してから os.Exit(1) を呼び出します。Pino の fatal() は終了前の最後のメッセージを想定し、そのレベルが有効で、出力先が flushSync() を備えていれば、同期フラッシュを試みます。実際に終了するかはアプリケーション側の処理で決まります。起動失敗や回復可能なリクエストエラーを記録するときは、API ごとの動作を確認しましょう。Go の log · Pino の fatal

ロガーから出力先までフィルターをたどる

Log4j 2 の通常の INFO しきい値では、INFO、WARN、ERROR、FATAL がレベル判定を通過できます。その後、Appender や別のフィルターがイベントを落とすこともあります。DEBUG が見つからなければ、まずロガーと出力先のしきい値を確認します。アプリケーションが出力していない記録は、コレクターでは取得できません。

通常のログに必要な処理時間が出ていない場合は、対象モジュールやインスタンスに絞って一時的に DEBUG または TRACE を有効にし、終了時刻を決めます。出力先やコレクターのフィルターはそのままの場合があるため、調査に必要な記録が届くかも確認します。実行中にログレベルを変更する

元のレベルを残して正規化する

数値の意味は形式ごとに異なります。RFC 5424 の syslog では、重大度は Emergency の 0 から Debug の 7 までです。OpenTelemetry の正規化済み SeverityNumber は、数値が大きいほど重大で、WARN は 13–16 です。SeverityText には元のラベルを残せます。syslog の Warning を表す 4 と OpenTelemetry の 4 は意味が違うため、横断検索の前に入力元ごとのマッピングを適用します。RFC 5424 の重大度 · OpenTelemetry ログデータモデル

たとえば、チェックアウトサービスの WARN を Guance の warning に変換する Pipeline を使うと、以下のようなレコードになります。元のラベルは別フィールドに残しています。

{"service":"checkout","operation":"check_inventory","outcome":"recovered","level":"WARN","status":"warning"}

DataKit ログコレクターのリファレンスでは、レベルを抽出できない場合の既定値は info で、表示上は trace と verbose を debug にまとめています。DataKit ログ収集ガイド(英語)には unknown になるという説明もあります。検出ルールを作る前に、警告とレベルのないレコードを実際の収集経路に流し、保存された status を確認してください。SECURITY のようにイベントの種類を表すラベルを使う場合は、分類と重大度を別々に残すと、両方を検索できます。

Guance のログエクスプローラーでサービスと正規化後の status を指定し、検出ルールの対象になる記録を確認します。再試行で回復するケースの増加は傾向として追い、購入手続きの失敗には別のしきい値や通知先を検討できます。エラーログの増加を利用者への影響として扱う前に、失敗件数をトラフィックやサービスレベル目標と照らし合わせます。Guance のログ検出 · ログ監視

最適なプランを相談する

お問い合わせ

コミュニティに参加

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

Guanceを試す

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

利用を開始

Guanceのプランを選択

コードリポジトリ