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トークンはマスクする：
"headers": { "Authorization": "Bearer *****" } - 一貫したフォーマットを維持
- JSON形式で統一し、ログ解析ツールと連携しやすくする。
- 処理時間を記録
execution_time_msを記録し、APIのパフォーマンス監視に活用。
8. まとめ
| 項目 | 説明 |
|---|---|
| 成功時ログ | APIリクエスト・レスポンス詳細を記録 |
| エラー時ログ | スタックトレースを含める |
| DBクエリログ | 実行クエリとパラメータを記録 |
| 外部APIログ | リクエストとレスポンスを記録 |
| 機密情報を記録しない | トークンやパスワードはマスク |
| JSONフォーマットで統一 | 構造化ログを出力 |
| 処理時間を記録 | execution_time_ms でAPIの遅延分析 |
適切なデバッグログを設計することで、APIのトラブルシューティングやパフォーマンス最適化がスムーズになります。