Menu
Amazon CloudWatch
User Guide

Use 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 in 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.

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

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

  2. Create or edit a graph or line widget.

  3. Choose Graphed metrics.

  4. Choose Add a math expression.

    A new line appears for the expression.

  5. For the Details column, type the math expression. The tables in the following section list the functions 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 e1-MIN(e1).

    You can change the value of Id. It can include numbers, letters, and underscore, and must start with a lowercase letter. Changing 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

  6. For the Label column of the expression, type a name that describes what the expression is calculating.

  7. After you have added the expressions you want, 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.

Metric Math Syntax and Functions

The following sections explain the functions available for metric math. All functions must be written in all-uppercase letters (such as AVG, while 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. Some functions in tables in the following sections produce either a scalar number or an array of time series. You can use these functions within a larger function that ultimately produces a single time series. For example, taking the AVG of a single time series produces a scalar number, so it cannot be the final expression result. But you could use it in the function m1-AVG(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 tables, every example in the Examples column is an expression that results in a single time series, to help show how functions that return scalar numbers or arrays of time series can be used as part of a valid expression that produces a single time series.

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 instance i-1234567890abcdef0 over the last three 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 that appear on the graph. You can use METRICS() within a larger expression. For example, the expression SUM(METRICS()) returns a time series (TS) that is the sum of the values of all the graphed metrics.

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)

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. Write all functions in uppercase letters.

The final result of any math expression must be a single time series. Some functions in the following table produce either a scalar number or an array of time series. You can use these functions within a larger function that ultimately produces a single time series. For example, taking the AVG of a single time series produces a scalar number, so it cannot be the final expression result. But you could use it in the function m1-AVG(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, to help show how functions that return scalar numbers or arrays of time series 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(m1-m2)

MIN(ABS([m1, m2]))

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 average 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)

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)

MIN(FILL(METRICS(), m2))

FLOOR

TS

TS[]

TS

TS[]

Returns the floor of each metric (the largest integer less than or equal to each value).

FLOOR(m1)

MIN(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 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())

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.

m1-MIN(m1)

MIN(METRICS())

PERIOD

TS

S

Returns the period of the metric in seconds. It supports only metrics passed as input, not input that are the results of other expressions.

m1/PERIOD(m1)

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 or an array of time series is not valid, as all final results of expressions must be a single 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.