Amazon API Gatewayのログとトレース総まとめ

この記事は、Japan AWS Jr. Champions Advent Calendar 2025 シリーズ1・6日目の記事となります。

2025 Japan AWS Jr. Championsに選出いただいてから、はやくも6ヶ月が過ぎました。
社内外の様々なイベントに巻き込んでいただき感謝の日々を過ごしている、Masedaです。

本記事では、API Gatewayの様々なログについて実際の結果を見ながら各機能の特徴と活用方法を詳しく解説します。

ログの有効化方法

API Gatewayのログは以下で有効化することができます。

ログを出力するにはAPI GatewayにIAM Roleを指定する必要があります。
RoleにアタッチするPolicyは「AmazonAPIGatewayPushToCloudWatchLogs」となります。

ロールARNをコピペして変更を保存。（なぜ選択式ではなくコピペ形式なのか謎…）

ログレベルの選択

CloudWatchログの設定では、以下の2つを選択することができます。

• エラーのみ
• エラーと情報ログ

また、「データトレース」・「詳細なメトリクス」・「カスタムのアクセスログ」・「X-Rayトレース」のオンオフを設定することができます。
これらのログは、CloudWatchロググループに以下の単位で保管されます。

API-Gateway-Execution-Logs_{API ID}

ここからは、各設定のオンオフによってどのようにログ出力が変化するのか見ていきましょう。

エラーログの検証

擬似的にエラーを発生させてみます。今回は統合先のLambda関数でエラーを発生させています。

import json

def lambda_handler(event, context):
    raise Exception("Test error for CloudWatch ERROR logging")

設定で「エラーのみ」とすると、ERRORレベルのみログが記録されます。（=正常リクエストについてはログ出力されません）
（言葉のとおりですね）

「データトレース」・「詳細なメトリクス」・「カスタムのアクセスログ」・「X-Rayトレース」をすべてオフにしているので詳細ログやメトリクスも出力されず、簡素なログのみ記録されます。

データトレース

さて、ここでデータトレースをオンにしてみます。

さきほどの簡素なログから大幅に出力が増えました。

データトレースでは、Method Request等の情報が追加されますが、公式ドキュメント記載のとおり、本番稼働用APIではデータトレースを有効にしないことをお勧めします。
理由は以下のためです。

このログはAPIのトラブルシューティングに役立ちますが、機密データが記録される可能性があります。

詳細なメトリクス

詳細なメトリクスをオンにすると、CloudWatch Metricsに以下のメトリクスが保存されます。

• Count:特定の期間のAPIリクエストの総数
• 5XXError:特定の期間にキャプチャされたサーバー側エラーの数
• 4XXError:特定の期間にキャプチャされたクライアント側エラーの数
• Latency:API Gatewayがクライアントからリクエストを受け取ってからクライアントにレスポンスを返すまでの時間
• IntegrationLatency:API Gateway がインテグレーションにリクエストを送信し、API Gateway がインテグレーションからレスポンスを受信するまでの時間差

CloudWatch > Metrics > ApiGatewayからメトリクスを確認してみましょう。

各種メトリクスを可視化することができました。

カスタムのアクセスログ

出力先のロググループARNと、どの情報を出力するかJSON形式等（他CLF, XML,CSV形式）で指定して設定します。

記録できる情報は以下公式ドキュメントをご確認ください。

今回は、以下の情報を取得しています。

{
  "requestId":"$context.requestId",
  "ip":"$context.identity.sourceIp",
  "userAgent":"$context.identity.userAgent",
  "requestTime":"$context.requestTime",
  "httpMethod":"$context.httpMethod",
  "resourcePath":"$context.resourcePath",
  "status":"$context.status",
  "responseLength":"$context.responseLength"
}

指定したロググループにカスタムログが出力されました。

余談

ロググループのARNをコピーすると、末尾に「:*」がひっつきますが、そのまま「アクセスログの送信先ARN」にペーストすると怒られます。コピペしたあと削除してあげましょう。

JSONをいつもの感覚で設定すると怒られます。（1行で記載する必要があります）

X-Rayトレース

X-Rayトレースを有効化すると、トレースマップが作成されます。

サービス依存関係が視覚的にわかりやすく、またレスポンス時間分布やエラー発生パターンを把握することができるため、パフォーマンスチューニングや障害分析に役立ちます。

おわりに

本記事では、API Gatewayの各種ログ設定について、実際の検証結果を基に解説しました。
今回の検証では「エラーのみ」を選択しましたが、「エラーと情報ログ」を有効化すると正常系リクエストのログも追えるようになります。
この記事がどなたかの助けになることを祈って終わりにします。よいクリスマスを。