How do I turn on CloudWatch Logs to troubleshoot my API Gateway REST API or WebSocket API?

Short description

To troubleshoot an API Gateway REST API or WebSocket API, use Amazon CloudWatch Logs. For information about the types of log formats, see CloudWatch log formats for API Gateway.

Note: HTTP APIs support only access logging. For more information, see Configure logging for HTTP APIs in API Gateway.

You can find the following information in the logs:

• Requests that your API receives
• Integration backend responses from your API
• The response that AWS Lambda authorizers provides
• The requestId for AWS integration endpoints
• Whether a provided API key was authorized

Resolution

Create an IAM role to send logs to CloudWatch

Complete the following steps:

1. Open the AWS Identity and Access Management (IAM) console.
2. In the navigation pane, choose Roles.
3. In the Roles pane, choose Create role.
4. On the Create role page, enter the following information:
   For Trusted entity, choose AWS Service.
   For use case, choose API Gateway, and then choose the API Gateway radio button.
   Choose Next.
5. Under Permissions policies, use the default AmazonAPIGatewayPushToCloudWatchLogs AWS managed policy that has all the required permissions.
6. Choose Next.
7. Under Name, review and create, enter the following information:
   For Role name, enter a name for the role.
   (Optional) For Role description, edit the description to your preferences.
   (Optional) Add tags.
   Choose Create role.
8. In the Roles pane, choose the role that you created.
9. In the Summary pane, note the role's ARN to use in the next section.

For information about permissions, see Permissions for CloudWatch logging.

Add the IAM role in the API Gateway console

Complete the following steps:

1. Open the API Gateway console.
2. In the APIs pane, choose the name of the REST API or WebSocket API, not the HTTP API.
3. In the navigation pane, choose Settings.
4. Under Settings, for CloudWatch log role ARN, enter the IAM role's ARN.
   Note: The CloudWatch Logs role is an AWS Region-level configuration that you use with all the APIs in the Region.
5. Choose Save.

Note: If you create multiple APIs across different Regions, then complete the preceding steps in each Region.

Turn on API logging and stage the API

Complete the following steps:

1. Open the API Gateway console.
2. In the navigation pane, choose APIs, and then select your API.
3. In the navigation pane, choose Stages, and then select your stage.
4. Under Logs and tracing, choose Edit.
5. Under CloudWatch logs, select a level from the dropdown menu.
   Note: For full request and response logs, select the Data tracing option with the logging level set to Error and info logs. It's a best practice not to turn on Data tracing for production APIs because data tracing can log sensitive data.
6. Choose Detailed metrics.
7. Under Custom Access Logging, complete the following steps:
   Select Enable Access Logging.
   For Access Log Destination ARN, enter the ARN of an Amazon Data Firehose or a CloudWatch log group.
   Note: Only REST APIs support the Firehose ARN.
8. Enter a log format.
9. Choose Save Changes.

Test your logging setup

Note: To send a new request to your API, use your client application or tools, such as the Postman app or wscat for WebSocket APIs.

Complete the following steps:

1. Open the CloudWatch console.
2. In the navigation pane, under Logs, choose Log groups.
3. For Log groups, select the log group of the API that you want to debug:
   For REST APIs, the log group name is in the API-Gateway-Execution-Logs_apiId/stageName format.
   For WebSocket APIs, the log group name is in the /aws/apigateway/apiId/stageName format.
   Note: The access logs are located in the log group that you specified when you turned on access logging.
4. In the Log streams list, select the log stream with the latest Last Event Time to view messages with the details of your request.

Related information

API Gateway mapping template and access logging variable reference

Monitor REST API execution with Amazon CloudWatch metrics

Monitor WebSocket API execution with CloudWatch metrics