APIのデバッグログの出力例と管理方法

APIのデバッグログは、APIの動作を詳細に記録し、開発やトラブルシューティングの際に役立ちます。開発環境では詳細なログを出力し、本番環境では出力を抑えるか制限を設けるのが一般的です。本記事では、APIのデバッグログの基本構造と具体的な出力例、保存・管理方法を紹介します。

---

1. デバッグログの基本構造

APIのデバッグログには、以下のような情報を含めるのが望ましいです。

項目	説明
timestamp	ログの発生日時 (ISO 8601)
log_level	ログのレベル (DEBUG, INFO, ERROR など)
event	処理の内容（例: API_REQUEST, DB_QUERY）
endpoint	APIのエンドポイント
method	HTTPメソッド (GET, POST など)
headers	リクエストヘッダー
request	リクエストボディ (JSON)
response	レスポンスデータ (JSON)
status	HTTPレスポンスコード
execution_time_ms	APIの処理時間 (ミリ秒)
client_ip	クライアントのIPアドレス
user_agent	クライアントのUser-Agent
stack_trace	エラー発生時のスタックトレース

---

2. デバッグログの出力例（成功時）

成功時ログ（APIリクエスト & レスポンス）

jsonコピーする編集する{
    "timestamp": "2025-01-27T10:00:00Z",
    "log_level": "DEBUG",
    "event": "API_REQUEST",
    "endpoint": "/users",
    "method": "GET",
    "headers": {
        "Authorization": "Bearer xyz123",
        "User-Agent": "Mozilla/5.0"
    },
    "request": {
        "limit": 10,
        "offset": 0
    },
    "response": {
        "users": [
            {
                "id": 1,
                "name": "John Doe",
                "email": "john.doe@example.com"
            },
            {
                "id": 2,
                "name": "Jane Doe",
                "email": "jane.doe@example.com"
            }
        ],
        "total": 100
    },
    "status": 200,
    "execution_time_ms": 85,
    "client_ip": "192.168.1.100",
    "user_agent": "Mozilla/5.0"
}

ポイント

• APIリクエストとレスポンスの詳細を記録。
• execution_time_ms を記録し、パフォーマンス分析に活用。
• headers や client_ip でリクエスト元を特定。

---

3. デバッグログの出力例（エラー時）

エラー時ログ（リソース未検出）

jsonコピーする編集する{
    "timestamp": "2025-01-27T10:05:00Z",
    "log_level": "DEBUG",
    "event": "API_ERROR",
    "endpoint": "/users/100",
    "method": "GET",
    "headers": {
        "Authorization": "Bearer xyz123",
        "User-Agent": "PostmanRuntime/7.29.0"
    },
    "request": {},
    "response": {
        "status": "error",
        "message": "User not found"
    },
    "status": 404,
    "execution_time_ms": 12,
    "client_ip": "192.168.1.101",
    "user_agent": "PostmanRuntime/7.29.0",
    "stack_trace": "UserNotFoundException at UserController.getUser(UserController.java:45)"
}

ポイント

• エラー内容 (response.message) を詳細に記録。
• HTTPステータス (status) を記録し、エラーハンドリングの分析が可能。
• エラーのスタックトレース (stack_trace) を記録し、原因を特定しやすくする。

---

4. デバッグログの出力例（データベースクエリ）

SQLクエリの記録

jsonコピーする編集する{
    "timestamp": "2025-01-27T10:10:00Z",
    "log_level": "DEBUG",
    "event": "DB_QUERY",
    "query": "SELECT * FROM users WHERE id = ?",
    "parameters": [100],
    "execution_time_ms": 5
}

ポイント

• SQLクエリの内容と実行時間 (execution_time_ms) を記録。
• parameters を記録し、デバッグしやすくする。

---

5. デバッグログの出力例（外部APIの呼び出し）

jsonコピーする編集する{
    "timestamp": "2025-01-27T10:15:00Z",
    "log_level": "DEBUG",
    "event": "EXTERNAL_API_REQUEST",
    "endpoint": "https://external-api.com/payment",
    "method": "POST",
    "request": {
        "user_id": 100,
        "amount": 5000
    },
    "response": {
        "status": "success",
        "transaction_id": "abc123"
    },
    "status": 200,
    "execution_time_ms": 300
}

ポイント

• 外部APIのリクエストとレスポンスを記録。
• execution_time_ms を記録し、APIレスポンスの遅延分析に活用。

---

6. デバッグログの保存場所と管理

保存先	説明
ファイル	/var/logs/api_debug.log など
データベース	logs テーブルに保存
クラウド	AWS CloudWatch, Google Cloud Logging
ログ収集ツール	Elasticsearch, Splunk, Datadog

ログのローテーション

• 日次 でローテーション。
• 7日間分を保存し、古いログは削除。
• 本番環境では DEBUG レベルのログは出力しない。

---

7. ベストプラクティス

• 適切なレベルで出力
  • 開発環境: DEBUG ログを有効化。
  • 本番環境: DEBUG ログは無効化 or 必要最低限に制限。
• 機密情報を記録しない
  • password、credit_card_number などは ログに記録しない。
  • JWTトークンはマスクする：
  jsonコピーする編集する"headers": { "Authorization": "Bearer *****" }
• 一貫したフォーマットを維持
  • JSON形式で統一し、ログ解析ツールと連携しやすくする。
• 処理時間を記録
  • execution_time_ms を記録し、APIのパフォーマンス監視に活用。

---

8. まとめ

項目	説明
成功時ログ	APIリクエスト・レスポンス詳細を記録
エラー時ログ	スタックトレースを含める
DBクエリログ	実行クエリとパラメータを記録
外部APIログ	リクエストとレスポンスを記録
機密情報を記録しない	トークンやパスワードはマスク
JSONフォーマットで統一	構造化ログを出力
処理時間を記録	execution_time_ms でAPIの遅延分析

適切なデバッグログを設計することで、APIのトラブルシューティングやパフォーマンス最適化がスムーズになります。