ロギングのベストプラクティス

アプリケーションとサービス全体で効果的なデバッグ、モニタリング、監査機能を確保するために、これらのロギング原則を適用してください。

構造化ロギング

• すべてのログ出力に構造化ロギング形式（JSON）を使用する
• すべてのログエントリ全体で一貫したフィールドを含める
• ログをマシン解析可能にしながら、人間が読める状態に保つ
• 構造化出力をネイティブでサポートするロギングライブラリを使用する
• ログメッセージの文字列連結を避け、構造化フィールドを使用する

標準ログフィールド

すべてのログエントリに以下のフィールドを含めます：

• timestamp: ISO 8601 形式（タイムゾーン付き）
• level: ログの重大度（DEBUG、INFO、WARN、ERROR、FATAL）
• message: イベントの人間が読める説明
• service: サービスまたはアプリケーションの名前
• version: アプリケーションバージョンまたはビルド識別子
• trace_id: 分散トレーシング相関 ID
• span_id: 現在のスパン識別子
• request_id: リクエストの一意識別子

ログレベル

適切なログレベルを一貫して使用します：

• DEBUG: 開発用の詳細な診断情報
• INFO: 通常の運用イベントと状態変化
• WARN: グレースフルに処理された予期しない状況
• ERROR: 現在の操作に影響するが、サービスには影響しない障害
• FATAL: 即座の対応が必要な重大な障害

コンテキスト伝播

• リクエストのライフサイクル内のすべてのログエントリにリクエストコンテキストを含める
• サービス境界を超えてトレース ID を伝播させる
• ユーザーが開始したアクション用にユーザーコンテキスト（匿名化）を追加する
• ドメインイベント用に関連するビジネスコンテキストを含める
• MDC（Mapped Diagnostic Context）または同等のコンテキスト管理を使用する

セキュリティとプライバシー

• 機密情報（パスワード、トークン、PII）をログに出力しない
• 参照が必要な場合は機密データをマスクまたは編集する
• データの機密性に適切なログアクセス制御を実装する
• データ保持ポリシーとコンプライアンス要件を検討する
• 機密システムのログアクセスを監査する

パフォーマンス考慮事項

• 非同期ロギングを使用してアプリケーションスレッドのブロッキングを回避する
• 本番環境での大量のデバッグログに対するログサンプリングを実装する
• レイテンシーとスループットのバランスを取るようにログをバッファリングする
• ロギングインフラストラクチャをボトルネック監視する
• 環境ごとに適切なログレベルを設定する

ログ集約

• すべてのサービスからのログを単一のプラットフォームに一元化する
• すべてのサービス全体で一貫したフォーマットを使用する
• ログローテーションと保持ポリシーを実装する
• 全文検索とフィルタリング機能を有効にする
• 重大なパターンに対するログベースのアラートを設定する

エラーログ

• メッセージ、コード、スタックトレースなど完全なエラーコンテキストを含める
• ラップされた/ネストされた例外のエラーチェーンをログに出力する
• 関連するリクエストと状態情報を含める
• レイヤー全体でのエラーログの重複を回避する
• エラー復旧アクションと結果をログに出力する

ベストプラクティス

• サービス境界でログを出力する（エントリーポイントとエグジットポイント）
• パフォーマンス分析用のタイミング情報を含める
• 設定変更とデプロイメントをログに出力する
• デバッグを支援するアクション可能なログメッセージを作成する
• ノイズを減らすためにロギングを定期的にレビューしてクリーンアップする

ログメッセージガイドライン

• 明確で説明的なメッセージを書く
• 関連する識別子（ユーザー ID、注文 ID など）を含める
• 「エラーが発生しました」のような汎用メッセージを避ける
• アプリケーション全体で一貫した用語を使用する
• 追加検索なしでイベントを理解するのに十分なコンテキストを含める

環境固有の設定

• Development: DEBUG レベル、コンソール出力、詳細フォーマット
• Staging: INFO レベル、構造化 JSON、完全なコンテキスト
• Production: INFO/WARN レベル、構造化 JSON、DEBUG のサンプリング