How do I find API Gateway REST API errors in my CloudWatch logs?

Last updated: 2021-02-23

I want to find a specific Amazon API Gateway REST API request failure in my Amazon CloudWatch logs. How can I do that?

Resolution

CloudWatch provides two types of API logging: access logging and execution logging. For more information on the different types of API logging, see CloudWatch log formats for API Gateway.

To find a specific API Gateway REST API request failure using CloudWatch logs, do the following.

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

To find a REST API request failure using CloudWatch access logs

1.    Set up CloudWatch API access logging using the API Gateway console.
Note: The following example uses the JSON CloudWatch log format and includes a message field for the $context.error.message context.

2.    Run the filter-log-events AWS CLI command on the API Gateway access logs using your preferred search utility.

Example filter-log-events command that uses the "grep" search utility for API Gateway access logs

aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep '17cb49b2-c061-11e9-bc30-f118c8b08d5f'

Important: Change the log-group-name to the access log group's name.

3.    Check the response to your filter-log-events command to identify errors. The command response will return an object with all of the $context variables you've mapped.

Example filter-log-events command response

{
    "requestId": "17cb49b2-c061-11e9-bc30-f118c8b08d5f",
    "ip": "1.2.3.4",
    "caller": "-",
    "user": "-",
    "requestTime": "28/Aug/2019:15:10:34 +0000",
    "httpMethod": "GET",
    "resourcePath": "/iam",
    "status": "403",
    "message": "Missing Authentication
            Token",
    "protocol": "HTTP/1.1",
    "responseLength": "42"
}

To find a REST API request failure using CloudWatch execution logs

1.    Set up CloudWatch API execution logging using the API Gateway console.
Important: To prevent storing sensitive information, make sure that you disable Log full requests/responses data before moving to production.

2.    Run the following cURL command to replicate the failed API request: 

Important: Replace abcd1234 with your API ID and us-east-1 with the AWS Region your API is in.

curl -X GET https://abcd1234.execute-api.us-east-1.amazonaws.com/dev/myapi -v

3.    Note the x-amzn-requestid value in the API response headers. This value is required in the next step.

Example API Gateway response headers

< content-type: application/json
< content-length: 41
< x-amzn-requestid: 17cb49b2-c061-11e9-bc30-f118c8b08d5f
< x-amz-apigw-id: eh7enHGIvHcFnPg=

4.    Run the filter-log-events AWS CLI command on the API Gateway execution logs using your preferred search utility.

Example filter-log-events command that uses the "grep" search utility for API Gateway execution logs

aws logs filter-log-events --log-group-name 'API-Gateway-Execution-Logs_2mg2xeej0a/test' | grep '17cb49b2-c061-11e9-bc30-f118c8b08d5f'

Important: Change the log-group-name to the access log group's name.

5.    Check the response to your filter-log-events command to identify errors. The following are examples of the type of error messages you may see:

Example API Gateway permissions errors

(b59c91c8-3386-4478-b2b4-c4d63191756e) Execution failed due to configuration error: Invalid permissions on Lambda function
(b59c91c8-3386-4478-b2b4-c4d63191756e) Gateway response type: DEFAULT_5XX with status code: 500
(b59c91c8-3386-4478-b2b4-c4d63191756e) Gateway response body: {"message": "Internal server error"}

Example API Gateway integration timeout errors

(2a1db04d-ac7c-463f-b9bd-478285467d58) Execution failed due to a timeout error
(2a1db04d-ac7c-463f-b9bd-478285467d58) Gateway response type: DEFAULT_5XX with status code: 504
(2a1db04d-ac7c-463f-b9bd-478285467d58) Gateway response body: {"message": "Endpoint request timed out"}

Example API Gateway backend integration errors

(631ff793-2c5b-413d-a31d-f2cd3f75708b) Endpoint response body before transformations: {"errorMessage": "division by zero", "errorType": "ZeroDivisionError", "stackTrace": [" File \"/var/task/lambda_function.py\", line 7, in lambda_handler\n c=a/b\n"]}
(631ff793-2c5b-413d-a31d-f2cd3f75708b) Lambda execution failed with status 200 due to customer function error: division by zero. Lambda request id: 7f0d8fc1-33ce-4bf9-8685-df78e179da5c
(631ff793-2c5b-413d-a31d-f2cd3f75708b) Gateway response type: DEFAULT_5XX with status code: 502
(631ff793-2c5b-413d-a31d-f2cd3f75708b) Gateway response body: {"message": "Internal server error"}

If you can't get the request ID

1.    Get the HTTP status code and/or the returned error message from the client-side application logs.

2.    Run the filter-log-events AWS CLI command on the API Gateway access logs. Use the "grep" search utility for either the HTTP status code or the returned error message.

Example filter-log-events command that uses the "grep" search utility for an HTTP status code

aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep '504'

Example filter-log-events command that uses the "grep" search utility for a returned error message from the client side

aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep 'Endpoint request timed out'

3.    Find the request ID in the access logs results.

4.    Follow the procedure in the Tracking API responses in the execution logs section.


Did this article help?


Do you need billing or technical support?