How can I use Amazon API Gateway logs for troubleshooting?

Last updated: 2022-12-07

I want to use Amazon API Gateway logs for troubleshooting API issues.

Short description

To troubleshoot an API Gateway REST API or WebSocket API, turn on execution logging and access logging using Amazon CloudWatch Logs. Make sure that you have attached all the required permissions to the API Gateway AWS Identity and Access Management (IAM) role. For instructions, see How do I turn on CloudWatch Logs for troubleshooting my API Gateway REST API or WebSocket API?

Note: HTTP APIs currently support access logging only, and logging setup is different for these APIs. For more information, see Configuring logging for an HTTP API.

Resolution

After you turn on logging, API Gateway automatically creates a CloudWatch log group named API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}. For more information, see CloudWatch log formats for API Gateway.

AWS Lambda authorizers

If you have Lambda authorizers turned on for your API, the logs indicate if the request is authorized and include the authorizer and request IDs.

Example authorized logs:

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

Example unauthorized logs:

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

Usage plans

After the Lambda authorizer logs, API Gateway verifies the usage plan for the API request. If you haven't configured a usage plan, then API requests aren't counted for throttling limits.

Example usage plan logs:

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

If you have configured APIs with API keys but the X-API-Key header is missing, then the logs return an error similar to the following:

API Key not authorized because method 'GET /' requires API Key and API 
Key is not associated with a Usage Plan for API Stage 
<api_id>/<stage>: API Key was required but not present

If you added the correct API key in the header but the request is throttled, then the logs return an error similar to the following:

API Key **********************************FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt. Limit: 5.00 Burst: 0
Method completed with status: 429

Request log types

Note: All request log types require turning on Log full requests/responses data in the execution logs.

Method request logs

Method request logs includes detailed information received by an API request including the request path, query parameter, request header, and request body.

Endpoint request logs

Endpoint request logs include detailed information received by an API request including the URI, request headers, and request body.

The data included in endpoint requests are sent to your backend integration for further processing.

Endpoint response logs

Endpoint response logs include the data returned by the backend integration including the status code, headers body, and Integration latency.

Method response logs

Method response logs includes the headers and body sent to the client after the transformation.

Important: API Gateway limits log events to 1024 bytes. Log events larger than 1024 bytes, such as request and response bodies, are truncated by API Gateway before submission to CloudWatch logs.