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

Last updated: 2020-11-10

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

Short description

To troubleshoot an API Gateway REST API or WebSocket API that you're developing, enable execution logging and access logging to 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 helpful information that you can use to identify and fix most errors with your APIs. This information includes:

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


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 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, on the APIs pane, choose the name of an API that you created.
  2. In the left navigation pane, at the bottom, 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 successfully.

Enable 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 enable execution logging:
    Select 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.
    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.
  4. Under Custom Access Logging, do the following to enable access logging:
    Select 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, you can choose CLF, JSON, XML, or CSV to see an example in that format.
  5. Choose Save Changes.
    Note: The console doesn't confirm that these settings are saved successfully.

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 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.
    Note: The access logs are located in the log group whose ARN you specified when you enabled access logging.
  4. In the list of Log Streams, choose the logs stream with the latest Last Event Time 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.