ログ設計指針#

1. 出力形式#

ログの集約と解析を容易にするため、全てのログを JSON形式 で標準出力（stdout）に出力する。

2. ログレベル#

レベル説明
FATALシステム停止を伴う致命的なエラー。即時通知対象。
ERROR継続は可能だが、期待しない動作が発生したエラー。要調査。
WARN異常ではないが、リトライが発生した際やリソース不足の予兆など。
INFO業務上の重要なイベント（ファイルアップロード完了等）。
DEBUG開発時のデバッグ情報。本番環境では出力しない。

3. 共通ログ項目#

全てのログには以下のフィールドを必須または推奨で含める。

  • timestamp: ISO8601形式の時刻
  • level: ログレベル
  • trace_id: リクエスト間を横断して追跡するためのユニークなID（相関ID）
  • request_id: 単一操作を識別するためのユニークなID（冪等性制御・キャンセル用）
  • user_id: ユーザー識別子（MVPでは対象外とし、nullまたは固定値を出力する）
  • message: ログの内容（人間が読める形式）
  • context: 関連する補足データ（メタデータ）

4. 追跡可能性（Observability）#

  • モノレポ内の各サービス間で X-Trace-Id ヘッダーを伝播させ、フロントエンドからバックエンドまでの処理を単一のトレースIDで追跡可能にする。
  • X-Request-Id ヘッダーも併せて伝播させ、単一操作のログを特定して追跡可能にする。

5. ログ出力の禁止事項 (PIIの保護)#

以下の情報は、セキュリティおよびプライバシー保護のため、ログに出力してはならない。

  • パスワード、アクセストークン、シークレットキー
  • クレジットカード情報
  • 個人情報（氏名、生年月日、住所、電話番号等）を直接特定できる情報
    • 必要がある場合はハッシュ化またはマスキング処理（例: k****@example.com）を行う。

6. ログの保存とモニタリング#

  • 保存期間: 運用要件に基づき、30日間（またはそれ以上）を標準とする。
  • 監視: ERROR以上のログが発生した場合、Slack等のチャットツールへ通知を行う。
Backward セキュリティ設計指針 運用設計指針 Forward