Using Metric Math
Metric math enables you to query multiple CloudWatch metrics and use math expressions
to
create new time series based on these metrics. You can visualize the resulting time
series on
the CloudWatch console and add them to dashboards. For an example using AWS Lambda
metrics, you could
divide the Errors
metric by the
Invocations
metric to get an error rate, and add the resulting time series to a graph on your
CloudWatch
dashboard.
You can also perform metric math programmatically, using the GetMetricData
API operation. For more information, see GetMetricData.
Adding a Math Expression to a CloudWatch Graph
You can add a math expression to a graph on your CloudWatch dashboard. Each graph is limited to a maximum of 100 metrics and expressions, so you can add a math expression only if the graph has 99 or fewer metrics.
To add a math expression to a graph

Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

Create or edit a graph or line widget.

Choose Graphed metrics.

Choose Add a math expression. A new line appears for the expression.

For the Details column, enter the math expression. The tables in the following section list the functions that you can use in the expression.
To use a metric or the result of another expression as part of the formula for this expression, use the value shown in the Id column: for example, m1+m2 or e1MIN(e1).
You can change the value of Id. It can include numbers, letters, and underscore, and it must start with a lowercase letter. Changing the value of Id to a more meaningful name can also make a graph easier to understand: for example, changing from m1 and m2 to errors and requests.

For the Label column of the expression, enter a name that describes what the expression is calculating.
If the result of an expression is an array of time series, each of those time series is displayed on the graph with a separate line, with different colors. Immediately under the graph is a legend for each line in the graph. For a single expression that produces multiple time series, the legend captions for those time series are in the format
ExpressionLabel MetricLabel
. For example, if the graph includes a metric with a label of Errors and an expression FILL(METRICS(), 0) that has a label of Filled With 0:, one line in the legend would be Filled With 0: Errors. To have the legend show only the original metric labels, setExpressionLabel
to be empty.When one expression produces an array of time series on the graph, you can't change the colors used for each of those time series.

After you have added the desired expressions, you can optionally simplify the graph by hiding some of the original metrics. To hide a metric or expression, clear the check box to the left of the Id field.
Metric Math Syntax and Functions
The following sections explain the functions available for metric math. All functions must be written in uppercase letters (such as AVG), and the Id field for all metrics and math expressions must start with a lowercase letter.
The final result of any math expression must be a single time series or an array of time series. Some functions produce a scalar number. You can use these functions within a larger function that ultimately produces a time series. For example, taking the AVG of a single time series produces a scalar number, so it can't be the final expression result. But you could use it in the function m1AVG(m1) to display a time series of the difference between each individual data point and the average value of that data point.
Data Type Abbreviations
Some functions are valid for only certain types of data. The abbreviations in the following list are used in the tables of functions to represent the types of data supported for each function:

S represents a scalar number, such as 2, 5, or 50.25

TS is a time series (a series of values for a single CloudWatch metric over time): for example, the
CPUUtilization
metric for instancei1234567890abcdef0
over the last 3 days 
TS[] is an array of time series, such as the time series for multiple metrics
The METRICS() Function
The METRICS() function returns all the metrics in the request. Math expressions aren't included.
You can use METRICS() within a larger expression that produces a single time series or an array of time series. For example, the expression SUM(METRICS()) returns a time series (TS) that is the sum of the values of all the graphed metrics. METRICS()/100 returns an array of time series, each of which is a time series showing each data point of one of the metrics divided by 100.
You can use the METRICS() function with a string to return only the graphed metrics that contain that string in their Id field. For example, the expression SUM(METRICS("errors")) returns a time series that is the sum of the values of all the graphed metrics that have ‘errors’ in their Id field. You can also use SUM([METRICS(“4xx”), METRICS(“5xx”)]) to match multiple strings.
Basic Arithmetic Functions
The following table lists the basic arithmetic functions that are supported. Missing values in time series are treated as 0. If the value of a data point causes a function to attempt to divide by zero, the data point is dropped.
Operation  Arguments  Examples 

Arithmetic operators: +  * / ^ 
S, S S, TS TS, TS S, TS[] TS, TS[] 
PERIOD(m1)/60 5 * m1 m1  m2 SUM(100/[m1, m2]) AVG([m1,m2]/m3) METRICS()*100 
Unary subtraction  
S TS TS[] 
5*m1 m1 SUM([m1, m2]) 
Functions Supported for Metric Math
The following table describes the functions you can use in math expressions. Enter all functions in uppercase letters.
The final result of any math expression must be a single time series or an array of time series. Some functions in tables in the following sections produce a scalar number. You can use these functions within a larger function that ultimately produces a time series. For example, taking the AVG of a single time series produces a scalar number, so it can't be the final expression result. But you could use it in the function m1AVG(m1) to display a time series of the difference between each individual data point and the average value of that data point.
In the following table, every example in the Examples column is an expression that results in a single time series or an array of time series. This shows how functions that return scalar numbers can be used as part of a valid expression that produces a single time series.
Function  Arguments  Return Type*  Description  Examples 

ABS 
TS TS[] 
TS TS[] 
Returns the absolute value of each data point. 
ABS(m1m2) MIN(ABS([m1, m2])) ABS(METRICS()) 
AVG 
TS TS[] 
S TS 
The AVG of a single time series returns a scalar representing the average of all the data points in the metric. The AVG of an array of time series returns a single time series. Missing values are treated as 0. 
SUM([m1,m2])/AVG(m2) AVG(METRICS()) 
CEIL 
TS TS[] 
TS TS[] 
Returns the ceiling of each metric (the smallest integer greater than or equal to each value). 
CEIL(m1) CEIL(METRICS()) SUM(CEIL(METRICS())) 
FILL 
TS, TS/S TS[], TS/S 
TS TS[] 
Fills the missing values of a metric with the specified filler value when the metric values are sparse. 
FILL(m1,10) FILL(METRICS(), 0) FILL(m1, MIN(m1)) 
FLOOR 
TS TS[] 
TS TS[] 
Returns the floor of each metric (the largest integer less than or equal to each value). 
FLOOR(m1) FLOOR(METRICS()) 
MAX 
TS TS[] 
S TS 
The MAX of a single time series returns a scalar representing the maximum value of all data points in the metric. The MAX value of an array of time series returns a single time series. 
MAX(m1)/m1 MAX(METRICS()) 
METRIC_COUNT 
TS[] 
S 
Returns the number of metrics in the time series array. 
m1/METRIC_COUNT(METRICS()) 
METRICS() 
null string 
TS[] 
The METRICS() function returns all the CloudWatch metrics in the request. Math expressions aren't included You can use METRICS() within a larger expression that produces a single time series or an array of time series. You can use the METRICS() function with a string to return only the graphed metrics that contain that string in their Id field. For example, the expression SUM(METRICS("errors")) returns a time series that is the sum of the values of all the graphed metrics that have ‘errors’ in their Id field. You can also use SUM([METRICS(“4xx”), METRICS(“5xx”)]) to match multiple strings. 
AVG(METRICS()) SUM(METRICS("errors")) 
MIN 
TS TS[] 
S TS 
The MIN of a single time series returns a scalar representing the minimum value of all data points in the metric. The MIN of an array of time series returns a single time series. 
m1MIN(m1) MIN(METRICS()) 
PERIOD 
TS 
S 
Returns the period of the metric in seconds. Valid input is metrics, not the results of other expressions. 
m1/PERIOD(m1) 
RATE 
TS TS[] 
TS TS[] 
Returns the rate of change of the metric per second. This is calculated as the difference between the latest data point value and the previous data point value, divided by the time difference in seconds between the two values. 
RATE(m1) RATE(METRICS()) 
SEARCH 
Search expression 
One or more TS 
Returns one or more time series that match a search criteria that you specify. The SEARCH function enables you to add multiple related time series to a graph with one expression. The graph is dynamically updated to include new metrics that are added later and match the search criteria. For more information, see Using Search Expressions in Graphs. 

STDDEV 
TS TS[] 
S TS 
The STDDEV of a single time series returns a scalar representing the standard deviation of all data points in the metric. The STDDEV of an array of time series returns a single time series. 
m1/STDDEV(m1) STDDEV(METRICS()) 
SUM 
TS TS[] 
S TS 
The SUM of a single time series returns a scalar representing the sum of the values of all data points in the metric. The SUM of an array of time series returns a single time series. 
SUM(METRICS())/SUM(m1) SUM([m1,m2]) SUM(METRICS("errors"))/SUM(METRICS("requests"))*100 
*Using only a function that returns a scalar number is not valid, as all final results of expressions must be a single time series or an array of time series. Instead, use these functions as part of a larger expression that returns a time series.
Using Metric Math with the GetMetricData API Operation
You can use GetMetricData
to perform calculations using math expressions,
as well as to retrieve large batches of metric data in one API call. For more information,
see GetMetricData.