# Get statistics for a metric
# CloudWatch statistics definitions
Statistics are metric data aggregations over specified periods of time. When you graph or retrieve the statistics for a metric, you specify the *Period* of time, such as five minutes, to use to calculate each statistical value. For example, if the **Period** is five minutes, the **Sum** is the sum of all sample values collected during the five-minute period, while the **Minimum** is the lowest value collected during the five-minute period.
CloudWatch supports the following statistics for metrics.
+ **SampleCount** is the number of data points during the period.
+ **Sum** is the sum of the values of the all data points collected during the period.
+ **Average** is the value of `Sum/SampleCount` during the specified period.
+ **Minimum** is the lowest value observed during the specified period.
+ **Maximum** is the highest value observed during the specified period.
+ **Percentile (p)** indicates the relative standing of a value in a dataset. For example, **p95** is the 95th percentile and means that 95 percent of the data within the period is lower than this value and 5 percent of the data is higher than this value. Percentiles help you get a better understanding of the distribution of your metric data.
+ **Trimmed mean (TM)** is the mean of all values that are between two specified boundaries. Values outside of the boundaries are ignored when the mean is calculated. You define the boundaries as one or two numbers between 0 and 100, up to 10 decimal places. The numbers can be absolute values or percentages. For example, **tm90** calculates the average after removing the 10% of data points with the highest values. **TM(2%:98%)** calculates the average after removing the 2% lowest data points and the 2% highest data points. **TM(150:1000)** calculates the average after removing all data points that are lower than or equal to 150, or higher than 1000.
+ **Interquartile mean (IQM)** is the trimmed mean of the *interquartile range*, or the middle 50% of values. It is equivalent to **TM(25%:75%)**.
+ **Winsorized mean (WM)** is similar to trimmed mean. However, with winsorized mean, the values that are outside the boundary are not ignored, but instead are considered to be equal to the value at the edge of the appropriate boundary. After this normalization, the average is calculated. You define the boundaries as one or two numbers between 0 and 100, up to 10 decimal places. For example, **wm98** calculates the average while treating the 2% of the highest values to be equal to the value at the 98th percentile. **WM(10%:90%)** calculates the average while treating the highest 10% of data points to be the value of the 90% boundary, and treating the lowest 10% of data points to be the value of the 10% boundary.
+ **Percentile rank (PR)** is the percentage of values that meet a fixed threshold. For example, **PR(:300)** returns the percentage of data points that have a value of 300 or less. **PR(100:2000)** returns the percentage of data points that have a value between 100 and 2000.
Percentile rank is exclusive on the lower bound and inclusive on the upper bound.
+ **Trimmed count (TC)** is the number of data points in the chosen range for a trimmed mean statistic. For example, **tc90** returns the number of data points not including any data points that fall in the highest 10% of the values. **TC(0.005:0.030)** returns the number of data points with values between 0.005 (exclusive) and 0.030 (inclusive).
Trimmed count can return a decimal value instead of an integer. This is because it is an interpolated, approximate value and can give fractional results.
+ **Trimmed sum (TS)** is the sum of the values of data points in a chosen range for a trimmed mean statistic. It is equivalent to (Trimmed Mean) \$1 (Trimmed count). For example, **ts90** returns the sum of the data points not including any data points that fall in the highest 10% of the values. **TS(80%:)** returns the sum of the data point values, not including any data points with values in the lowest 80% of the range of values.
**Note**
For Trimmed Mean, Trimmed Count, Trimmed Sum, and Winsorized Mean, if you define two boundaries as fixed values instead of percentages, the calculation includes values equal to the higher boundary, but does not include values equal to the lower boundary.
## Syntax
For Trimmed Mean, Trimmed Count, Trimmed Sum, and Winsorized Mean, the following syntax rules apply:
+ Using parentheses with one or two numbers with percent signs defines the boundaries to use as the values in the data set that fall in between the two percentiles that you specify. For example, **TM(10%:90%)** uses only the values between the 10th and 90th percentiles. **TM(:95%)** uses the values from the lowest end of the data set up to the 95th percentile, ignoring the 5% of data points with the highest values.
+ Using parenthesis with one or two numbers without percent signs defines the boundaries to use as the values in the data set that fall in between the explicit values that you specify. For example, **TC(80:500)** uses only the values that are between 80 (exclusive) and 500 (inclusive). **TC(:0.5)** uses only the values that equal 0.5 or are lower.
+ Using one number without parentheses calculates using percentages, ignoring data points that are higher than the specified percentile. For example, **tm99** calculates the mean while ignoring the 1% of the data points with the highest value. It is the same as **TM(:99%)**.
+ Trimmed mean, Trimmed Count, Trimmed Sum, and Winsorized Mean can all be abbreviated using uppercase letters when specifying a range, such as **TM(5%:95%)**, **TM(100:200)**, or **TM(:95%)**. They can only be abbreviated using lowercase letters when you specifying only one number, such as **tm99**.
## Statistics use cases
+ **Trimmed mean** is most useful for metrics with a large sample size, such as webpage latency. For example, **tm99** disregards extreme high outliers that could result from network problems or human errors, to give a more accurate number for the average latency of typical requests. Similarly, **TM(10%:)** disregards the lowest 10% of latency values, such as those resulting from cache hits. And **TM(10%:99%)** excludes both of these types of outliers. We recommend that you use trimmed mean for monitoring latency.
+ It is a good idea to keep watch on trimmed count whenever you are using trimmed mean, to make sure that the number of values being used in your trimmed mean calculations are enough to be statistically significant.
+ Percentile rank enables you to put values into "bins" of ranges, and you can use this to manually create a histogram. To do this, break your values down into various bins, such as **PR(:1)**, **PR(1:5)**, **PR(5:10)**, and **PR(10:)**. Put each of these bins into a visualization as bar charts, and you have a histogram.
Percentile rank is exclusive on the lower bound and inclusive on the upper bound.
## Percentiles versus trimmed mean
A percentile such as **p99** and a trimmed mean such as **tm99** measure similar, but not identical values. Both **p99** and **tm99** ignore the 1% of the data points with the highest values, which are considered outliers. After that, **p99** is the **maximum value of the remaining 99%, while **tm99** is the *average* of the remaining 99%. If you are looking at the latency of web requests, **p99** tells you the worst customer experience, ignoring outliers, while **tm99** tells you the average customer experience, ignoring outliers.
Trimmed mean is a good latency statistic to watch if you are looking to optimize your customer experience.
## Requirements to use percentiles, trimmed mean, and some other statistics
CloudWatch needs raw data points to calculate the following statistics:
+ Percentiles
+ Trimmed mean
+ Interquartile mean
+ Winsorized mean
+ Trimmed sum
+ Trimmed count
+ Percentile rank
If you publish data for a custom statistics using a statistic set instead of raw data, you can retrieve these types of statistics for this data only if one of the following conditions is true:
+ The SampleCount value of the statistic set is 1 and Min, Max, and Sum are all equal.
+ The Min and Max are equal, and Sum is equal to Min multiplied by SampleCount.
The following AWS services include metrics that support these types of statistics.
+ API Gateway
+ Application Load Balancer
+ Amazon EC2
+ Elastic Load Balancing
+ Kinesis
+ Amazon RDS
Additionally, these type of statistics are not available for metrics when any of the metric values are negative numbers.
## Examples
The following examples show you how to get statistics for the CloudWatch metrics for your resources, such as your EC2 instances.
**Topics**
# Get statistics for a specific resource
The following example shows you how to determine the maximum CPU utilization of a specific EC2 instance.
**Requirements**
+ You must have the ID of the instance. You can get the instance ID using the Amazon EC2 console or the [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) command.
+ By default, basic monitoring is enabled, but you can enable detailed monitoring. For more information, see [Enable or Disable Detailed Monitoring for Your Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html) in the *Amazon EC2 User Guide*.
**To display the average CPU utilization for a specific instance using the console**
1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. In the navigation pane, choose **Metrics**, **All metrics**.
1. Select the **EC2** metric namespace.
![\[Select the EC2 metrics namespace\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/images/metric_view_categories.png)
1. Select the **Per-Instance Metrics** dimension.
![\[View the metric dimensions for Amazon EC2\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/images/metric_view_metric_category.png)
1. In the search field, enter **CPUUtilization** and press Enter. Select the row for the specific instance, which displays a graph for the `CPUUtilization` metric for the instance. To change the name of the graph, choose the pencil icon. To change the time range, select one of the predefined values or choose **custom**.
![\[Graph a single metric\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/images/metric_statistics_ec2_instance.png)
1. To change the statistic, choose the **Graphed metrics** tab. Choose the column heading or an individual value and then choose one of the statistics or predefined percentiles, or specify a custom percentile (for example, **p99.999**).
![\[Change the statistic for a metric\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/images/metric_statistics_ec2_instance_statistic_period.png)
1. To change the period, choose the **Graphed metrics** tab. Choose the column heading or an individual value, and then choose a different value.
**To get the CPU utilization per EC2 instance using the AWS CLI**
Use the [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) command as follows to get the `CPUUtilization` metric for the specified instance.
```
aws cloudwatch get-metric-statistics --namespace AWS/EC2 --metric-name CPUUtilization \
--dimensions Name=InstanceId,Value=i-1234567890abcdef0 --statistics Maximum \
--start-time 2016-10-18T23:18:00 --end-time 2016-10-19T23:18:00 --period 360
```
The returned statistics are 6-minute values for the requested 24-hour time interval. Each value represents the maximum CPU utilization percentage for the specified instance for a particular 6-minute time period. The data points aren't returned in chronological order. The following shows the beginning of the example output (the full output includes data points for every 6 minutes of the 24-hour period).
```
{
"Datapoints": [
{
"Timestamp": "2016-10-19T00:18:00Z",
"Maximum": 0.33000000000000002,
"Unit": "Percent"
},
{
"Timestamp": "2016-10-19T03:18:00Z",
"Maximum": 99.670000000000002,
"Unit": "Percent"
},
{
"Timestamp": "2016-10-19T07:18:00Z",
"Maximum": 0.34000000000000002,
"Unit": "Percent"
},
...
],
"Label": "CPUUtilization"
}
```
# Aggregate statistics across resources
You can aggregate the metrics for AWS resources across multiple resources. Metrics are completely separate between Regions, but you can use metric math to aggregate similar metrics across Regions. For more information, see [Using math expressions with CloudWatch metrics](using-metric-math.md).
For example, you can aggregate statistics for your EC2 instances that have detailed monitoring enabled. Instances that use basic monitoring aren't included. Therefore, you must enable detailed monitoring (at an additional charge), which provides data in 1-minute periods. For more information, see [Enable or Disable Detailed Monitoring for Your Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html) in the *Amazon EC2 User Guide*.
This example shows you how to get the average CPU usage for your EC2 instances. Because no dimension is specified, CloudWatch returns statistics for all dimensions in the `AWS/EC2` namespace. To get statistics for other metrics, see [AWS services that publish CloudWatch metrics](aws-services-cloudwatch-metrics.md).
**Important**
This technique for retrieving all dimensions across an AWS namespace doesn't work for custom namespaces that you publish to CloudWatch. With custom namespaces, you must specify the complete set of dimensions that are associated with any given data point to retrieve statistics that include the data point.
**To display average CPU utilization for your EC2 instances**
1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. In the navigation pane, choose **Metrics**, **All metrics**.
1. Choose the **EC2** namespace and choose **Across All Instances**.
1. Select the row that contains `CPUUtilization`, which displays a graph for the metric for all your EC2 instances. To change the name of the graph, choose the pencil icon. To change the time range, select one of the predefined values or choose **custom**.
![\[Metrics aggregated across your EC2 instances\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/images/metric_aggregated_instances.png)
1. To change the statistic, choose the **Graphed metrics** tab. Choose the column heading or an individual value and then choose one of the statistics or predefined percentiles, or specify a custom percentile (for example, **p95.45**).
1. To change the period, choose the **Graphed metrics** tab. Choose the column heading or an individual value and then choose a different value.
**To get average CPU utilization across your EC2 instances using the AWS CLI**
Use the [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-staticstics.html) command as follows:
```
aws cloudwatch get-metric-statistics --namespace AWS/EC2 --metric-name CPUUtilization --statistics "Average" "SampleCount" \
--start-time 2016-10-11T23:18:00 --end-time 2016-10-12T23:18:00 --period 3600
```
The following is example output:
```
{
"Datapoints": [
{
"SampleCount": 238.0,
"Timestamp": "2016-10-12T07:18:00Z",
"Average": 0.038235294117647062,
"Unit": "Percent"
},
{
"SampleCount": 240.0,
"Timestamp": "2016-10-12T09:18:00Z",
"Average": 0.16670833333333332,
"Unit": "Percent"
},
{
"SampleCount": 238.0,
"Timestamp": "2016-10-11T23:18:00Z",
"Average": 0.041596638655462197,
"Unit": "Percent"
},
...
],
"Label": "CPUUtilization"
}
```
# Aggregate statistics by Auto Scaling group
You can aggregate statistics for the EC2 instances in an Auto Scaling group. Metrics are completely separate between Regions, but you can use CloudWatch metric math to aggregate and transform metrics from multiple Regions. You can also use the cross-account dashboard to perform metric math on metrics from different accounts.
This example shows you how to get the total bytes written to disk for one Auto Scaling group. The total is computed for 1-minute periods for a 24-hour interval across all EC2 instances in the specified Auto Scaling group.
**To display DiskWriteBytes for the instances in an Auto Scaling group using the console**
1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. In the navigation pane, choose **Metrics**, **All metrics**.
1. Choose the **EC2** namespace and then choose **By Auto Scaling Group**.
1. Select the row for the **DiskWriteBytes** metric and the specific Auto Scaling group, which displays a graph for the metric for the instances in the Auto Scaling group. To change the name of the graph, choose the pencil icon. To change the time range, select one of the predefined values or choose **custom**.
![\[Metrics aggregated across an Auto Scaling group\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/images/metric_aggregated_auto_scaling.png)
1. To change the statistic, choose the **Graphed metrics** tab. Choose the column heading or an individual value and then choose one of the statistics or predefined percentiles, or specify a custom percentile (for example, **p95.45**).
1. To change the period, choose the **Graphed metrics** tab. Choose the column heading or an individual value and then choose a different value.
**To get DiskWriteBytes for the instances in an Auto Scaling group using the AWS CLI**
Use the [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) command as follows.
```
aws cloudwatch get-metric-statistics --namespace AWS/EC2 --metric-name DiskWriteBytes
--dimensions Name=AutoScalingGroupName,Value=my-asg --statistics "Sum" "SampleCount" \
--start-time 2016-10-16T23:18:00 --end-time 2016-10-18T23:18:00 --period 360
```
The following is example output.
```
{
"Datapoints": [
{
"SampleCount": 18.0,
"Timestamp": "2016-10-19T21:36:00Z",
"Sum": 0.0,
"Unit": "Bytes"
},
{
"SampleCount": 5.0,
"Timestamp": "2016-10-19T21:42:00Z",
"Sum": 0.0,
"Unit": "Bytes"
}
],
"Label": "DiskWriteBytes"
}
```
# Aggregate statistics by Amazon Machine Image (AMI)
You can aggregate statistics for the EC2 instances that have detailed monitoring enabled. Instances that use basic monitoring aren't included. For more information, see [Enable or Disable Detailed Monitoring for Your Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html) in the *Amazon EC2 User Guide*.
This example shows you how to determine average CPU utilization for all instances that use the specified AMI. The average is over 60-second time intervals for a one-day period.
**To display the average CPU utilization by AMI using the console**
1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. In the navigation pane, choose **Metrics**, **All metrics**.
1. Choose the **EC2** namespace and then choose **By Image (AMI) Id**.
1. Select the row for the `CPUUtilization` metric and the specific AMI, which displays a graph for the metric for the specified AMI. To change the name of the graph, choose the pencil icon. To change the time range, select one of the predefined values or choose **custom**.
![\[Metrics aggregated by AMI\]](http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/images/metric_aggregated_ami.png)
1. To change the statistic, choose the **Graphed metrics** tab. Choose the column heading or an individual value and then choose one of the statistics or predefined percentiles, or specify a custom percentile (for example, **p95.45**).
1. To change the period, choose the **Graphed metrics** tab. Choose the column heading or an individual value and then choose a different value.
**To get the average CPU utilization by AMI using the AWS CLI**
Use the [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) command as follows.
```
aws cloudwatch get-metric-statistics --namespace AWS/EC2 --metric-name CPUUtilization \
--dimensions Name=ImageId,Value=ami-3c47a355 --statistics Average \
--start-time 2016-10-10T00:00:00 --end-time 2016-10-11T00:00:00 --period 3600
```
The operation returns statistics that are one-hour values for the one-day interval. Each value represents an average CPU utilization percentage for EC2 instances running the specified AMI. The following is example output.
```
{
"Datapoints": [
{
"Timestamp": "2016-10-10T07:00:00Z",
"Average": 0.041000000000000009,
"Unit": "Percent"
},
{
"Timestamp": "2016-10-10T14:00:00Z",
"Average": 0.079579831932773085,
"Unit": "Percent"
},
{
"Timestamp": "2016-10-10T06:00:00Z",
"Average": 0.036000000000000011,
"Unit": "Percent"
},
...
],
"Label": "CPUUtilization"
}
```