# Monitor REST API execution with Amazon CloudWatch metrics CloudWatch metrics You can monitor API execution by using CloudWatch, which collects and processes raw data from API Gateway into readable, near-real-time metrics. These statistics are recorded for a period of 15 months so you can access historical information and gain a better perspective on how your web application or service is performing. By default, API Gateway metric data is automatically sent to CloudWatch in one-minute periods. For more information, see [What Is Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) in the *Amazon CloudWatch User Guide*. The metrics reported by API Gateway provide information that you can analyze in different ways. The following list shows some common uses for the metrics that are suggestions to get you started: + Monitor the **IntegrationLatency** metrics to measure the responsiveness of the backend. + Monitor the **Latency** metrics to measure the overall responsiveness of your API calls. + Monitor the **CacheHitCount** and **CacheMissCount** metrics to optimize cache capacities to achieve a desired performance. **Topics** + [ # Amazon API Gateway dimensions and metrics ](api-gateway-metrics-and-dimensions.md) + [ # View CloudWatch metrics with the API dashboard in API Gateway ](how-to-api-dashboard.md) + [ # View API Gateway metrics in the CloudWatch console ](metrics_dimensions_view_in_cloud_watch.md) + [ # View API Gateway log events in the CloudWatch console ](view-cloudwatch-log-events-in-cloudwatch-console.md) + [ # Monitoring tools in AWS for API Gateway ](monitoring_automated_manual.md) # Amazon API Gateway dimensions and metrics The metrics and dimensions that API Gateway sends to Amazon CloudWatch are listed below. For more information, see [Monitor REST API execution with Amazon CloudWatch metrics](monitoring-cloudwatch.md). ## API Gateway metrics Amazon API Gateway sends metric data to CloudWatch every minute. The `AWS/ApiGateway` namespace includes the following metrics. | Metric | Description | | --- | --- | | 4XXError | The number of client-side errors captured in a given period. API Gateway counts modified gateway response status codes as 4XXError errors. The `Sum` statistic represents this metric, namely, the total count of the 4XXError errors in the given period. The `Average` statistic represents the 4XXError error rate, namely, the total count of the 4XXError errors divided by the total number of requests during the period. The denominator corresponds to the Count metric (below). Unit: Count | | 5XXError | The number of server-side errors captured in a given period. The `Sum` statistic represents this metric, namely, the total count of the 5XXError errors in the given period. The `Average` statistic represents the 5XXError error rate, namely, the total count of the 5XXError errors divided by the total number of requests during the period. The denominator corresponds to the Count metric (below). Unit: Count | | CacheHitCount | The number of requests served from the API cache in a given period. The `Sum` statistic represents this metric, namely, the total count of the cache hits in the given period. The `Average` statistic represents the cache hit rate, namely, the total count of the cache hits divided by the total number of requests during the period. The denominator corresponds to the Count metric (below). Unit: Count | | CacheMissCount | The number of requests served from the backend in a given period, when API caching is enabled. The `Sum` statistic represents this metric, namely, the total count of the cache misses in the given period. The `Average` statistic represents the cache miss rate, namely, the total count of the cache misses divided by the total number of requests during the period. The denominator corresponds to the Count metric (below). Unit: Count | | Count | The total number API requests in a given period. The `SampleCount` statistic represents this metric. Unit: Count | | IntegrationLatency | The time between when API Gateway relays a request to the backend and when it receives a response from the backend. Unit: Millisecond | | Latency | The time between when API Gateway receives a request from a client and when it returns a response to the client. The latency includes the integration latency and other API Gateway overhead. Unit: Millisecond | ## Dimensions for metrics You can use the dimensions in the following table to filter API Gateway metrics. **Note** API Gateway removes non-ASCII characters from the ApiName dimension before sending metrics to CloudWatch. If the APIName contains no ASCII characters, the API ID is used as the ApiName. | Dimension | Description | | --- | --- | | ApiName | Filters API Gateway metrics for the REST API with the specified API name. | | ApiName, Method, Resource, Stage | Filters API Gateway metrics for the API method with the specified API name, stage, resource, and method. API Gateway will not send these metrics unless you have explicitly enabled detailed CloudWatch metrics. In the console, choose a stage, and then for **Logs and tracing**, select **Edit**. Select **Detailed metrics**, and then choose **Save changes**. Alternatively, you can call the [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) AWS CLI command to update the `metricsEnabled` property to `true`. Enabling these metrics will incur additional charges to your account. For pricing information, see [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing/). | | ApiName, Stage | Filters API Gateway metrics for the API stage resource with the specified API name and stage. | # View CloudWatch metrics with the API dashboard in API Gateway View metrics with the API dashboard You can use the API dashboard in the API Gateway Console to display the CloudWatch metrics of your deployed API in API Gateway. These are shown as a summary of API activity over time. **Topics** + [ ## Prerequisites ](#how-to-api-dashboard-prerequisites) + [ ## Examine API activities in the dashboard ](#how-to-api-dashboard-console) ## Prerequisites 1. You must have an API created in API Gateway. Follow the instructions in [Develop REST APIs in API Gateway](rest-api-develop.md). 1. You must have the API deployed at least once. Follow the instructions in [Deploy REST APIs in API Gateway](how-to-deploy-api.md). ## Examine API activities in the dashboard 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose an API. 1. In the main navigation pane, choose **Dashboard**. 1. For **Stage**, choose the desired stage. 1. Choose **Date range** to specify a range of dates. 1. Refresh, if needed, and view individual metrics displayed in separate graphs titled **API calls**, **Latency**, **Integration latency**, **Latency**, **4xx error** and **5xx error**. **Tip** To examine method-level CloudWatch metrics, make sure that you have enabled CloudWatch Logs on a method level. For more information about how to set up method-level logging, see [Override stage-level settings](set-up-stages.md#how-to-method-override). # View API Gateway metrics in the CloudWatch console View metrics in the CloudWatch console Metrics are grouped first by the service namespace, and then by the various dimension combinations within each namespace. To view the metrics at the method-level for your API, turn on detailed metrics. For more information, see [Modify stage settings](set-up-stages.md#how-to-stage-settings). **To view API Gateway metrics using the CloudWatch console** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. If necessary, change the AWS Region. From the navigation bar, select the Region where your AWS resources reside. 1. In the navigation pane, choose **Metrics**. 1. In the **All metrics** tab, choose **API Gateway**. 1. To view metrics by stage, choose the **By Stage** panel. Then, select your APIs and metric names. 1. To view metrics by specific API, choose the **By Api Name** panel. Then, select your APIs and metric names. **To view metrics using the AWS CLI** 1. Use the following [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) command to list metrics: ``` aws cloudwatch list-metrics --namespace "AWS/ApiGateway" ``` After you create a metric, allow up to 15 minutes for the metric to appear. To see metric statistics sooner, use [get-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html) or [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html). 1. Use the following [get-metrics-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) command to view the average over a period of time using 5 minute intervals: ``` aws cloudwatch get-metric-statistics --namespace AWS/ApiGateway --metric-name Count --start-time 2011-10-03T23:00:00Z --end-time 2017-10-05T23:00:00Z --period 300 --statistics Average ``` # View API Gateway log events in the CloudWatch console View log event in the CloudWatch console The following section explains the necessary prerequisites and how to view API Gateway log events in the CloudWatch console. ## Prerequisites 1. You must have an API created in API Gateway. Follow the instructions in [Develop REST APIs in API Gateway](rest-api-develop.md). 1. You must have the API deployed and invoked at least once. Follow the instructions in [Deploy REST APIs in API Gateway](how-to-deploy-api.md) and [Invoke REST APIs in API Gateway](how-to-call-api.md). 1. You must have CloudWatch Logs enabled for a stage. Follow the instructions in [Set up CloudWatch logging for REST APIs in API Gateway](set-up-logging.md). ## To view logged API requests and responses using the CloudWatch console 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. If necessary, change the AWS Region. From the navigation bar, select the Region where your AWS resources reside. For more information, see [Regions and Endpoints](http://docs.aws.amazon.com/general/latest/gr/rande.html). 1. In the navigation pane, choose **Logs**, **Log groups**. 1. Under the **Log Groups** table, choose a log group of the **API-Gateway-Execution-Logs\$1\$1rest-api-id\$1/\$1stage-name\$1** name. 1. Under the **Log Streams** table, choose a log stream. You can use the timestamp to help locate the log stream of your interest. 1. Choose **Text** to view raw text or choose **Row** to view the event row by row. **Important** CloudWatch lets you delete log groups or streams. Do not manually delete API Gateway API log groups or streams; let API Gateway manage these resources. Manually deleting log groups or streams may cause API requests and responses not to be logged. If that happens, you can delete the entire log group for the API and redeploy the API. This is because API Gateway creates log groups or log streams for an API stage at the time when it is deployed. # Monitoring tools in AWS for API Gateway AWS provides various tools that you can use to monitor API Gateway. You can configure some of these tools to do the monitoring for you automatically, while other tools require manual intervention. We recommend that you automate monitoring tasks as much as possible. ## Automated monitoring tools in AWS Automated monitoring tools You can use the following automated monitoring tools to watch API Gateway and report when something is wrong: + **Amazon CloudWatch Alarms** – Watch a single metric over a time period that you specify, and perform one or more actions based on the value of the metric relative to a given threshold over a number of time periods. The action is a notification sent to an Amazon Simple Notification Service (Amazon SNS) topic or Amazon EC2 Auto Scaling policy. CloudWatch alarms do not invoke actions simply because they are in a particular state; the state must have changed and been maintained for a specified number of periods. For more information, see [Monitor REST API execution with Amazon CloudWatch metrics](monitoring-cloudwatch.md). + **Amazon CloudWatch Logs** – Monitor, store, and access your log files from AWS CloudTrail or other sources. For more information, see [What is CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) in the *Amazon CloudWatch User Guide*. + **Amazon EventBridge (formerly called CloudWatch Events)** – Match events and route them to one or more target functions or streams to make changes, capture state information, and take corrective action. For more information, see [What Is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) in the *EventBridge User Guide*. + **AWS CloudTrail Log Monitoring** – Share log files between accounts, monitor CloudTrail log files in real time by sending them to CloudWatch Logs, write log processing applications in Java, and validate that your log files have not changed after delivery by CloudTrail. For more information, see [Working with CloudTrail Log Files](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html) in the *AWS CloudTrail User Guide*. ## Manual monitoring tools Manual tools Another important part of monitoring API Gateway involves manually monitoring those items that the CloudWatch alarms don't cover. The API Gateway, CloudWatch, and other AWS console dashboards provide an at-a-glance view of the state of your AWS environment. We recommend that you also check the log files on API execution. + API Gateway dashboard shows the following statistics for a given API stage during a specified period of time: + **API Calls** + **Cache Hit**, only when API caching is enabled. + **Cache Miss**, only when API caching is enabled. + **Latency** + **Integration Latency** + **4XX Error** + **5XX Error** + The CloudWatch home page shows: + Current alarms and status + Graphs of alarms and resources + Service health status In addition, you can use CloudWatch to do the following: + Create [customized dashboards](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html) to monitor the services you care about + Graph metric data to troubleshoot issues and discover trends + Search and browse all your AWS resource metrics + Create and edit alarms to be notified of problems ## Creating CloudWatch alarms to monitor API Gateway Creating alarms You can create a CloudWatch alarm that sends an Amazon SNS message when the alarm changes state. An alarm watches a single metric over a time period you specify, and performs one or more actions based on the value of the metric relative to a given threshold over a number of time periods. The action is a notification sent to an Amazon SNS topic or Auto Scaling policy. Alarms invoke actions for sustained state changes only. CloudWatch alarms do not invoke actions simply because they are in a particular state; the state must have changed and been maintained for a specified number of periods.