How do I enable CloudWatch Logs for troubleshooting my API Gateway API?

Last updated: 2019-09-26

I need to debug errors with an Amazon API Gateway API that I'm developing. How do I enable logging to troubleshoot my API?

Short Description

To troubleshoot an API Gateway API that you're developing, enable execution logging to Amazon CloudWatch Logs. Execution logs contain helpful information that you can use to identify and fix most errors with Amazon API Gateway APIs. This information includes:

To enable these logs, create an AWS Identity and Access Management (IAM) role that gives API Gateway permission to read and write logs to CloudWatch, and then enable logging for your specific API and stage.

Resolution

Create an IAM role for logging to CloudWatch

  1. In the 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 the service that will use this role, choose API Gateway.
    Choose Next: Permissions.
  4. Under Attached permissions policies, note that the AWS managed policy AmazonAPIGatewayPushToCloudWatchLogs is selected by default. This policy has all the required permissions.
  5. Choose Next: Tags.
  6. Optionally add tags if you prefer, and then choose Next: Review.
  7. 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.
  8. On the Roles pane, in the search bar, enter the name of the role that you created, and then choose the role from the search results.
  9. 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, in the left navigation pane, choose Settings.
  2. For CloudWatch log role ARN, paste the IAM role ARN that you copied.
  3. Choose Save.
    Note: The console doesn't confirm that the ARN is saved successfully.

Enable logging for your API and stage

  1. In the API Gateway console, find the Stage Editor.
  2. On the Stage Editor pane, choose the Logs/Tracing tab.
  3. On the Logs/Tracing tab, under CloudWatch Settings, select the Enable CloudWatch Logs check box.
  4. For Log level, choose INFO to generate logs for all requests. Or, choose ERROR to generate logs only for requests to your API that result in an error.
  5. Select the Log full requests/responses data check box for a REST API. Or, select the Log full message data check box for a WebSocket API.
  6. Choose Save Changes.
    Note: The console doesn't confirm that these settings are saved successfully.

For more information, see Set up API Logging Using the API Gateway Console.

Test your logging setup

  1. Make a new request to your API Gateway API using your client application or a tool like the Postman app or wscat (for WebSocket APIs).
  2. In the CloudWatch console, in the left navigation pane, choose Logs.
  3. In the list of Log Groups, choose the log group of the API that you're debugging.
    For a REST API, the log group's name is in this format: API-Gateway-Execution-Logs_apiId/stageName.
    For a WebSocket API, the log group's name is in this format: /aws/apigateway/apiId/stageName.
  4. In the list of Log Streams, choose the logs stream with the latest Last Event Time to see the execution of the request you made and its relative information.

For more information, see View API Gateway Log Events in the CloudWatch Console.