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

5 minute read

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:

The requests that your API receives
The 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 for logging to CloudWatch

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

2. On the Roles pane, choose Create role.

3. On the Create role page, do the following:
For Trusted entity type, choose AWS Service.
For use case, choose API Gateway.
Choose the API Gateway radio button.
Choose Next.

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

5. Choose Next.

6. Under Name, review and create, do the following:
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.

7. 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.

8. On the Summary pane, copy the Role ARN. You 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. This is either a REST API or a WebSocket API (not an HTTP API).

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, on the APIs pane, choose the name of an API that you created.

2. In the left navigation pane, choose Stage. Then, select your desired stage name.

3. Choose the Logs/Tracing tab.

4. 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.

5. 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 an Amazon Kinesis Data Firehose (this is only supported in REST APIs) or a CloudWatch log group.

Enter a Log Format. For guidance, choose CLF, JSON, XML, or CSV to see an example in that format.

6. 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 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 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.