Logging observability

Logging & Observability

本番運用を見据えたログ設計・実装のためのスキル。「何を」「どのレベルで」「どう構造化して」残すかを判断する。バグそのものの調査手順は systematic-debugging、エラー処理の設計は error-handling-robustness を使う。

使うタイミング

• 新機能にログを追加するとき
• console.log / print によるデバッグ出力を本番コードに残さないよう置き換えるとき
• 障害調査・監視のためのログ設計をレビューするとき
• ログに機密情報が混入していないか点検するとき

手順

ステップ1：ログレベルを正しく選ぶ

レベル	使う場面
ERROR	処理が失敗し、人間の対応が必要な事象（リトライで回復しない外部障害、想定外の例外）
WARN	処理は継続できるが注意が必要な事象（リトライ発生、フォールバック使用、非推奨API使用）
INFO	ビジネス上意味のある通常イベント（リクエスト受付、ジョブ開始/終了、状態遷移）
DEBUG	開発時のみ必要な詳細情報。本番ではデフォルト無効にする

判断基準：「このログを見た運用担当者がすぐアクションを取るべきか」でERROR/WARNを分け、「後から障害調査で必要になりそうか」でINFO/DEBUGを分ける。

ステップ2：構造化ログにする

1. 本番コードから console.log / print を排除し、構造化ロガー（例：winston, structlog, zerolog等プロジェクトの標準）を採用する。
2. ログは自由記述の文字列ではなく、キー・バリューのフィールドとして出力する（例：{event: "order_created", order_id: "ord_123", user_id: "usr_456", duration_ms: 42}）。文字列連結でメッセージを組み立てない。
3. 全ログにタイムスタンプ・ログレベル・リクエストID（トレースID）を必須フィールドとして付与し、1つのリクエストのログを横断的に追跡できるようにする。
4. ログローテーション・保持期間を運用要件として明示的に設定する（無制限に溜め続けない）。

ステップ3：境界（バウンダリ）で何を残すかを決める

以下の境界を通過する箇所には最低限のログを入れる。

• 外部APIへのリクエスト／レスポンス（成功・失敗・レイテンシ）
• DBへの書き込み系操作の成否
• 認証・認可の成否（誰が・何に・成功/失敗したか）
• 非同期ジョブ・キューの開始/完了/失敗
• リトライ・フォールバックが発動した瞬間（WARNレベル）

逆に、境界を通過しない内部の細かい処理（ループの1イテレーションごと等）をINFOで出さない。ノイズになり本当に重要なログが埋もれる。

ステップ4：秘密情報・PIIを絶対にログへ出さない

実装中・レビュー中に必ずチェックする。

• パスワード、APIキー、トークン、Cookie、セッションIDをそのまま出力していないか
• クレジットカード番号、マイナンバー等の機微情報を出力していないか
• 氏名・メールアドレス・電話番号等のPIIを出す必要がある場合、マスキング（例：u***@example.com）またはハッシュ化しているか
• エラーオブジェクトを丸ごとログに出すとき、内部に機密情報（リクエストヘッダのAuthorization等）が含まれていないか確認したか
• ログ出力用のフィールドをホワイトリスト方式で選び、オブジェクト全体をJSON.stringify的にダンプしていないか

判断基準：「このログが第三者に漏洩したとき、何か悪用できる情報が含まれるか」を自問する。含まれるなら出力しない。

ステップ5：エラーログの中身を実行可能にする

• エラーログには「何が」「なぜ」失敗したかに加え、対処のヒント（どの入力・どの依存先が問題だったか）を含める。
• スタックトレースは本番でも記録する（ユーザーには見せないが、ログには残す）。
• 同一エラーが連発する場合に備え、エラーの発生箇所を一意に特定できるフィールド（エラーコード、発生関数名）を付与する。

チェックリスト（実装・レビュー時）

• console.log / print によるデバッグ出力が本番コードに残っていないか
• ログレベルが「アクションの緊急度」に応じて正しく選ばれているか
• 構造化（キー・バリュー）形式で出力しているか
• リクエストID等でログを横断追跡できるか
• 秘密情報・PIIが平文で出力されていないか
• ログローテーション・保持期間が設定されているか

アンチパターン集

アンチパターン	現実
すべてをINFOまたはERRORで出す	本当に対応が必要なログが埋もれ、アラート疲れ（alert fatigue）を招く
デバッグ用のconsole.logをそのまま本番に残す	構造化されておらず検索・集計できない。本番のログ基盤に混入するとノイズになる
エラーオブジェクトを丸ごとダンプする	リクエストヘッダやトークンが誤って漏洩するリスクがある。フィールドを選んで出力する
ユーザーのメールアドレス・氏名を平文でログに残す	PII漏洩リスク。マスキングかハッシュ化が必要
ログにトレースIDを付けない	1つのリクエストが複数サービス・複数行のログにまたがったとき、追跡できず障害調査が長引く
「後で見返すかもしれない」で全部DEBUGログを本番でも有効にする	ログ量が肥大化しストレージコストと検索性能を悪化させる。本番はデフォルト無効にする

出典

• elsewhencode/project-guidelines（MIT License）— 構造化ロガー採用、console.log排除、ログローテーションの方針を要約。