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

Last updated: 2021-03-10

I need to debug errors with an Amazon API Gateway REST API or WebSocket API that I'm developing. How do I turn on logging to troubleshoot my API?

Short description

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

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.

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

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

Resolution

Create an IAM role for logging to CloudWatch

1.    In the AWS Identity and Access Management (IAM) console, in the left navigation pane, choose Roles.

2.    On the Roles pane, choose Create role.

3.    On the Create role page, do the following:
For Select type of trusted entity, choose AWS Service.
For Choose a use case, choose API Gateway.
For Select your use case, choose API Gateway.
Choose Next: Permissions.

4.    Under Attached permissions policies, note that the AWS managed policy AmazonAPIGatewayPushToCloudWatchLogs is selected by default. The policy has all the required permissions.

5.    Choose Next: Tags.

6.    (Optional) Add tags.

7.    Choose Next: Review.

8.    Under Review, do the following:
For Role name, enter a meaningful name for the role.
(Optional) For Role description, edit the description to your preferences.
Choose Create role.

9.    On the Roles pane, in the search bar, enter the name of the role that you created. Then, choose the role from the search results.

10.    On the Summary pane, copy the Role ARN. You'll need this Amazon Resource Name (ARN) in the next section.

For more information, see Permissions for CloudWatch Logging.

Add the IAM role in the API Gateway console

Note: If you're developing multiple APIs across different AWS Regions, complete these steps in each Region.

1.    In the API Gateway console, on the APIs pane, choose the name of an API that you created.

2.    In the left navigation pane, at the bottom, below the Client Certificates section, choose Settings.

3.    Under Settings, for CloudWatch log role ARN, paste the IAM role ARN that you copied.

4.    Choose Save.
Note: The console doesn't confirm that the ARN is saved.

Turn on logging for your API and stage

1.    In the API Gateway console, find the Stage Editor for your API.

2.    On the Stage Editor pane, choose the Logs/Tracing tab.

3.     On the Logs/Tracing tab, under CloudWatch Settings, do the following to turn on execution logging:
Choose the Enable CloudWatch Logs check box.
For Log level, choose INFO to generate execution logs for all requests. Or, choose ERROR to generate execution logs only for requests to your API that result in an error.
For REST APIs, choose the Log full requests/responses data check box. Or, for WebSocket APIs, choose the Log full message data check box.

4.    Under Custom Access Logging, do the following to turn on access logging:
Choose the Enable Access Logging check box.
For Access Log Destination ARN, enter the ARN of a CloudWatch log group or an Amazon Kinesis Data Firehose stream.
Enter a Log Format. For guidance, choose CLF, JSON, XML, or CSV to see an example in that format.

5.    Choose Save Changes.
Note: The console doesn't confirm that settings are saved.

For more information, see Set up CloudWatch API logging using the API Gateway Console.

Test your logging setup

1.    Send a new request to your API using your client application or a tool such as the Postman app or wscat (for WebSocket APIs).

2.    In the CloudWatch console, in the left navigation pane, under Logs, choose Log Groups.

3.    In the list of Log Groups, choose the log group of the API that you're debugging.
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 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 will allow 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.