How do I turn on CloudWatch Logs for troubleshooting my API Gateway REST API or WebSocket API?

Short description

To troubleshoot an API Gateway REST API or WebSocket API, use Amazon CloudWatch Logs to turn on execution logging and access logging.

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

Execution logs contain information that you can use to identify and troubleshoot most API errors. For example, the logs can contain the following information:

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

Access logs contain details about who accessed your API and how they accessed it. You can also use the logs for troubleshooting API errors. For more information about each type of logging, see CloudWatch log formats for API Gateway.

Resolution

Create an IAM role to log to CloudWatch

To create an AWS Identity and Access Management (IAM) role to send logs to CloudWatch, complete the following steps:

1. Open the IAM console.
2. In the navigation pane, choose Roles.
3. On 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.
   Select the API Gateway radio button.
   Choose Next.
5. Under Permissions Policies, note that the AWS managed policy AmazonAPIGatewayPushToCloudWatchLogs is selected by default. The policy 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. On the Roles pane, in the search bar, enter the name of the role that you created. Then, choose the role.
9. On the Summary pane, copy the Role ARN. You need this ARN in the next section.

For more information, see Permissions for CloudWatch logging.

Add the IAM role in the API Gateway console

To add the IAM role to the API Gateway console, complete the following steps:

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

Note: If you develop multiple APIs across different AWS Regions, then complete these steps in each AWS Region.

Turn on logging for your API and stage

To turn on logging for your API and stage, 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. Then, select your stage.
4. Under Logs and tracing, choose Edit.
5. Under CloudWatch logs, complete the following tasks to turn on execution logging:
   From the dropdown list, choose your log level:
   Choose Errors only to generate execution logs only for requests to your API that result in an error.
   Choose Error and info logs to generate execution logs for all requests.
   Choose Full requests and response logs to generate detailed logging for all events.
   Note: Full requests and response logs is useful for troubleshooting, but can log sensitive data. It's a best practice to not use Full requests and response logs for production APIs.
6. Under Custom Access Logging, complete the following tasks to turn on access logging:
   Select the Enable Access Logging check box.
   For Access Log Destination ARN, enter the ARN of an Amazon Kinesis Data Firehose or a CloudWatch log group.
   Note: The ARN of Amazon Kinesis Data Firehose is supported only in REST APIs.
7. Enter a Log Format.
8. Choose Save Changes.

For more information, see CloudWatch log formats for API Gateway.

Test your logging setup

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

To test your logging setup, complete the following steps:

1. Open the CloudWatch console.
2. In the navigation pane, under Logs, choose Log Groups.
3. In the list of Log Groups, choose the log group of the API that you want to debug.
   For REST APIs, the log group's name is in the following format: API-Gateway-Execution-Logs_apiId/stageName.
   For WebSocket APIs, the log group's name is in the following format: /aws/apigateway/apiId/stageName.
   Note: The access logs are located in the log group whose ARN that you specified when you turned on access logging.
4. In the list of Log Streams, choose the logs stream with the latest Last Event Time. This selection allows you to see messages with the execution or access details of your request.

For more information, see View API Gateway log events in the CloudWatch console.

Related information

Setting up CloudWatch logging for a REST API in API Gateway

API Gateway mapping template and access logging variable reference

Monitoring REST API execution with Amazon CloudWatch metrics

Monitoring WebSocket API execution with CloudWatch metrics