API Gateway の REST API または WebSocket API のトラブルシューティングのために CloudWatch Logs をオンにするにはどうすればよいですか?

所要時間3分

開発している Amazon API Gateway の REST API または WebSocket API のエラーをデバッグする必要があります。API をトラブルシューティングするためにログ記録を有効にするにはどうすればよいですか?

簡単な説明

API ゲートウェイ REST API または WebSocket API のトラブルシューティングを行うには、Amazon CloudWatch Logs を使用して、実行ログ記録およびアクセスログ記録を有効にします。

注: HTTP API は現在、アクセスログ記録のみをサポートしており、これらの API ではログ記録の設定が異なります。詳細については、「HTTP API のログ記録の設定」をご参照ください。

実行ログには、ほとんどの API エラーの識別とトラブルシューティングに使用できる情報が含まれています。例:

API が受け取るリクエスト
API からの統合バックエンドレスポンス
AWS Lambda オーソライザーが提供するレスポンス
AWS 統合エンドポイントのための requestId
提供された API キーが認証されたかどうかについての情報

アクセスログには、API にアクセスしたユーザーとそのアクセス方法に関する詳細が含まれます。ログは、API エラーのトラブルシューティングにも使用できます。ログ記録の各タイプの詳細については、「CloudWatch log formats for API Gateway」(API Gateway の CloudWatch ログ形式) を参照してください。

解決方法

CloudWatch へのログ記録用の IAM ロールを作成する

1. AWS Identity and Access Management (IAM) コンソールのナビゲーションペインで、[Roles] (ロール) を選択します。

2. [ロール] ペインで、[ロールの作成] を選択します。

3. [Create role] (ロールの作成) ページで、次の手順を実行します。
信頼されたエンティティタイプとして [AWS のサービス] を選択します。
ユースケースとして[API ゲートウェイ] を選択します。
[API ゲートウェイ] ラジオボタンを選択します。
[次へ] を選択します。

4. [Permissions policies] (アクセス権限ポリシー) では、AWS が管理するポリシーである AmazonAPIGatewayPushToCloudWatchLogs がデフォルトで選択されていることに注意してください。ポリシーには、必要なアクセス権限のすべてがあります。

5. [次へ] を選択します。

6. [名前、確認、作成] で、次の操作を行います。
[ロール名] に、ロールの名前を入力します。
(オプション) [ロールの説明] の説明を希望に応じて編集します。
(オプション) [tags] (タグ) を追加します。
[ロールの作成] を選択します。

7. [Roles] (ロール) ウィンドウの検索バーで、作成したロールの名前を入力します。その後、検索結果からロールを選択します。

8. [Summary] (概要) ペインで [Role ARN] (ロール ARN) をコピーします。これは、次のセクションの [Amazon Resource Name (ARN)] (Amazon リソースネーム (ARN)) で必要になります。

詳細については、「Permissions for CloudWatch logging」(CloudWatch のログ記録の許可) を参照してください。

API Gateway コンソールで IAM ロールを追加する

注: 異なる AWS リージョン間で複数の API を開発している場合は、各リージョンでこれらのステップを完了してください。

1. API Gateway コンソールの [APIs] (API) ペインで、作成した API の名前を選択します。これは、REST API または WebSocket API (HTTP API ではない) のいずれかです。

2. 左側のナビゲーションウィンドウの下部にある [Client Certificates] (クライアント証明書) セクションで、[Settings] (設定) を選択します。

3. [Settings] (設定) で、[CloudWatch log role ARN] (CloudWatch ログのロール ARN) に、コピーした IAM ロール ARN を貼り付けます。

4. [Save] (保存) を選択します。
注: コンソールは ARN が保存されたことを確認しません。

API とステージのログ記録を有効にする

1. API Gateway コンソールの [APIs] (API) ペインで、作成した API の名前を選択します。

2. ナビゲーションペインで、[ステージ] を選択します。次に、希望するステージ名を選択します。

3. [Logs/Tracing] (ログ/トレース) タブを選択します。

4. [Logs/Tracing] (ログ/トレース) タブの [CloudWatch Settings] (CloudWatch 設定) で、以下を実行して実行ログ記録を有効にします。
[Enable CloudWatch Logs] (CloudWatch ログを有効化) チェックボックスにチェックを入れます。
[Log level] (ログレベル) には、すべてのリクエストの実行ログを生成するために [INFO] を選択します。または、[ERROR] を選択して、エラーになった API へのリクエストのみの実行ログを生成します。
REST API の場合は、[Log full requests/responses data] (リクエスト/レスポンスデータ全体をログ記録) チェックボックスにチェックを入れます。または、WebSocket API の場合は、[Log full message data] (メッセージデータをすべてログに記録する) チェックボックスにチェックを入れます。

5. [Custom Access Logging] (カスタムアクセスのログ記録) で、以下を実行してアクセスログを有効にします。
[Enable Access Logging] (アクセスログ記録の有効化) チェックボックスにチェックを入れます。
[Access Log Destination ARN] (アクセスログの宛先 ARN) で、Amazon Kinesis Data Firehose (これは REST API でのみサポートされています) または CloudWatch ロググループの ARN を入力します。

[Log Format] (ログの形式) を入力します。ガイダンスについて、その形式の例を確認するには、[CLF]、[JSON]、[XML]、または [CSV] を選択します。

6. [Save Changes] (変更を保存) を選択します。
注: コンソールは設定が保存されたことを確認しません。

詳細については、「Set up CloudWatch API logging using the API Gateway console」(API Gateway コンソールを使用して CloudWatch API ログ記録をセットアップする) を参照してください。

ログ記録の設定をテストする

1. クライアントアプリケーション、または Postman アプリや wscat (WebSocket API 向け) などのツールを使用して、API への新しいリクエストを送信します。

2. CloudWatch コンソールの左にあるナビゲーションペインの [Logs] (ログ) で [Log Groups] (ロググループ) を選択します。

3. [Log Groups] (ロググループ) リストで、デバッグする API のロググループを選択します。
REST API については、ロググループの名前が API-Gateway-Execution-Logs_apiId/stageName 形式になります。
WebSocket API については、ロググループの名前が /aws/apigateway/apiId/stageName 形式になります。
注: アクセスログは、アクセスログ記録を有効にしたときに ARN を指定したロググループにあります。

4. [Log Streams] (ログストリーム) のリストで、最新の [Last Event Time] (最終イベント時刻) のログストリームを選択します。この選択により、リクエストの実行またはアクセスの詳細を含むメッセージを表示できます。

詳細については、「View API Gateway log events in the CloudWatch console」(API Gateway ログイベントを CloudWatch コンソールで表示する) を参照してください。