How can I troubleshoot latency issues for my edge-optimized API endpoint in API Gateway?

Short description

To find the source of latency for an edge-optimized API endpoint, determine how long each of the following parts of the connection path takes:

Important: These connection path steps apply only to edge-optimized API endpoints, and not to Regional API endpoints. Edge-optimized APIs are accessed through an Amazon CloudFront distribution. Regional API endpoints aren't accessed through CloudFront.

1. Start of connection to the DNS name resolution
2. Start of connection to the Transmission Control Protocol (TCP) handshake to connect to CloudFront
3. Start of connection to the Secure Sockets Layer (SSL) handshake to connect to CloudFront
4. Start of connection to sending the client HTTP request to CloudFront
5. Start of connection to the first byte transferred from CloudFront
6. Total time for the request and response to the API
7. Time for API Gateway to process the request and respond to the CloudFront edge location
8. Time for the integration endpoint to respond to the HTTP request from API Gateway
9. Time for API Gateway to respond to the CloudFront edge location, and for CloudFront to respond to the client

The parts of the connection path that take the longest are the source of the latency.

Note: You can use AWS X-Ray to trace and analyze user requests as they travel through your Amazon API Gateway REST APIs to underlying services. API Gateway supports X-Ray tracing for all API Gateway REST API endpoint types in the AWS Regions where X-Ray is available. To see all the Regions where X-Ray is available, see the AWS Region table.

Resolution

Run the curl_for_latency Bash script

To determine the duration of steps 1-6 in your API's connection path process, run the curl_for_latency Bash script on GitHub.

Important: Make sure that you replace the URL, HTTP method, and parameters values to match the information for your API.

The script returns the time period that it takes for your API to complete the following connection path steps:

1. Start of connection to the DNS name resolution ("time_namelookup")
2. Start of connection to the TCP handshake to connect to CloudFront ("time_connect")
3. Start of connection to the SSL handshake to connect to CloudFront ("time_appconnect")
4. Start of connection to sending the client HTTP request to CloudFront ("time_pretransfer")
5. Start of connection to the first byte transferred from CloudFront ("time_starttransfer")
6. Total time for the request and response to the API ("time_total")

After you identify the events that are contributing to the latency, see How do I troubleshoot and reduce increased latency from CloudFront?

Verify how long it takes API Gateway to process the request and respond to the CloudFront edge location

Review the Latency metric for your API in the CloudWatch console. Then, configure the Latency metrics graph settings for 1-minute interval and Maximum to see the longest processing time within a one-minute time period.

For instructions, see View API Gateway metrics in the CloudWatch console.

Verify how long it takes for the integration endpoint to respond to the HTTP request from API Gateway

Review the IntegrationLatency metric in the CloudWatch console. Then, configure the IntegrationLatency graph settings for 1-minute interval and Maximum to see the longest processing time within a one-minute time period.

-or-

If you have CloudWatch logging activated for your API, then review the logs for a line item that's similar to the following:

Received response. Integration latency: 325 ms

You can also add $context variables with access logging for additional latency troubleshooting.

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

API Gateway requests integrated with Lambda

If you're using AWS Lambda with API Gateway and you see a high IntegrationLatency metric, review your Lambda function's CloudWatch Logs. High latency must be addressed when an API endpoint that’s integrated with a Lambda function takes too long to send responses to a client. Cold starts in Lambda functions aren't recorded in the function's duration metric, so your API's integration latency might be longer than the function's duration. To see the duration of your function with a cold start, use AWS X-Ray.

For more information, see How do I troubleshoot high latency in my API Gateway requests that are integrated with Lambda?

Verify how long it takes API Gateway to respond to the CloudFront edge location, and for CloudFront to respond to the client

Take the total time for the request and response to the API ("time_total"), and then subtract the following:

• Start of connection to sending the client HTTP request to CloudFront ("time_pretransfer")
• Time for API Gateway to process the request and respond to the CloudFront edge location (the Latency metric for your API)

The result is how long it takes API Gateway to respond to the CloudFront edge location, and for CloudFront to respond to the client.

---

Related information

Working with metrics for HTTP APIs

Amazon API Gateway dimensions and metrics

Monitoring WebSocket API execution with CloudWatch metrics

How can I use Amazon API Gateway logs for troubleshooting?