logging-best-practices

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

これらのロギング原則を適用して、アプリケーションやサービス全体で効果的なデバッグ、監視、監査を実現しましょう。

構造化ログ

• すべてのログ出力に構造化形式（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 など）を含めます
• 「エラーが発生しました」のような汎用的なメッセージは避けます
• アプリケーション全体で一貫した用語を使用します
• 追加の検索をしなくてもイベントを理解できるだけのコンテキストを含めます

環境固有の設定

• 開発：DEBUG レベル、コンソール出力、詳細なフォーマット
• ステージング：INFO レベル、構造化 JSON、完全なコンテキスト
• 本番：INFO/WARN レベル、構造化 JSON、DEBUG のサンプリング