View a markdown version of this page

Math expressions with metrics - Amazon CloudWatch
Add a math expression to a CloudWatch graphMetric math syntax and functionsUsing IF expressionsUse metric math with the GetMetricData API operationAnomaly detection on metric math

Math expressions with metrics

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. Using AWS Lambda metrics as an example, you could divide the Errors metric by the Invocations metric to get an error rate. Then 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.

Add 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 using a maximum of 500 metrics and expressions, so you can add a math expression only if the graph has 499 or fewer metrics. This applies even if not all the metrics are displayed on the graph.

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. There needs to be at least one metric in the graph.

  3. Choose Graphed metrics.

  4. Choose Math expression, Start with empty expression. A new line appears for the expression.

  5. In the new line, under the Details column, enter the math expression. The tables in the Metric Math Syntax and Functions 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 e1-MIN(e1).

    You can change the value of Id. It can include numbers, letters, an underscore, and 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 m1 and m2 to errors and requests.

    Tip

    Choose the down arrow next to Math Expression to see a list of supported functions, which you can use when creating your expression.

  6. 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 Expression-Label Metric-Label. 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, set Expression-Label 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.

  7. After you have added the desired expressions, you can 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 m1-AVG(m1) to display a time series of the difference between each individual data point and the average value in the 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.

  • String[] is an array of strings.

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 a 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(METRICS())

METRICS()*100

Unary subtraction -

S

TS

TS[]

-5*m1

-m1

SUM(-[m1, m2])

Comparison and logical operators

You can use comparison and logical operators with either a pair of time series or a pair of single scalar values. When you use a comparison operator with a pair of time series, the operators return a time series where each data point is either 0 (false) or 1 (true). If you use a comparison operator on a pair of scalar values, a single scalar value is returned, either 0 or 1.

When comparison operators are used between two time series, and only one of the time series has a value for a particular time stamp, the function treats the missing value in the other time series as 0.

You can use logical operators in conjunction with comparison operators, to create more complex functions.

The following table lists the operators that are supported.

Type of operator Supported operators

Comparison operators

==

!=

<=

>=

<

>

Logical operators

AND or &&

OR or ||

To see how these operators are used, suppose you have two time series: metric1 has values of [30, 20, 0, 0] and metric2 has values of [20, -, 20, -] where - indicates that there is no value for that timestamp.

Expression Output

(metric1 < metric2)

0, 0, 1, 0

(metric1 >= 30)

1, 0, 0, 0

(metric1 > 15 AND metric2 > 15)

1, 0, 0, 0

Functions supported for metric math

The following table describes the functions that 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 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 or an array of time series. These examples show 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 Supported for cross-account?

ABS

TS

TS[]

TS

TS[]

Returns the absolute value of each data point.

ABS(m1-m2)

MIN(ABS([m1, m2]))

ABS(METRICS())

 ✓

ANOMALY_DETECTION_BAND

TS

TS, S

TS[]

Returns an anomaly detection band for the specified metric. The band consists of two time series, one representing the upper limit of the "normal" expected value of the metric, and the other representing the lower limit. The function can take two arguments. The first is the ID of the metric to create the band for. The second argument is the number of standard deviations to use for the band. If you don't specify this argument, the default of 2 is used. For more information, see Using CloudWatch anomaly detection.

ANOMALY_DETECTION_BAND(m1)

ANOMALY_DETECTION_BAND(m1,4)

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.

Note

We recommend that you do not use this function in CloudWatch alarms if you want the function to return a scalar. For example, AVG(m2). Whenever an alarm evaluates whether to change state, CloudWatch attempts to retrieve a higher number of data points than the number specified as Evaluation Periods. This function acts differently when extra data is requested.

To use this function with alarms, especially alarms that have Auto Scaling actions, we recommend that you set the alarm to use M out of N datapoints, where M < N.

SUM([m1,m2])/AVG(m2)

AVG(METRICS())

 ✓

CEIL

TS

TS[]

TS

TS[]

Returns the ceiling of each metric. The ceiling is the smallest integer greater than or equal to each value.

CEIL(m1)

CEIL(METRICS())

SUM(CEIL(METRICS()))

 ✓

DATAPOINT_COUNT

TS

TS[]

S

TS

Returns a count of the data points that reported values. This is useful for calculating averages of sparse metrics.

Note

We recommend that you do not use this function in CloudWatch alarms. Whenever an alarm evaluates whether to change state, CloudWatch attempts to retrieve a higher number of data points than the number specified as Evaluation Periods. This function acts differently when extra data is requested.

SUM(m1) / DATAPOINT_COUNT(m1)

DATAPOINT_COUNT(METRICS())

 ✓

DB_PERF_INSIGHTS

String, String, String

String, String, String[]

TS (if given a single string)

TS[] (if given an array of strings)

Returns Performance Insights Counter metrics for databases such as Amazon Relational Database Service and Amazon DocumentDB (with MongoDB compatibility). This function returns the same amount of data that you can get by directly querying the Performance Insights APIs. You can use these metrics in CloudWatch for graphing and creating alarms.

Important

When you use this function, you must specify the Unique Database Resource ID of the database. This is different than the database identifier. To find the database resource ID in the Amazon RDS console, choose the DB instance to see its details. Then choose the Configuration tab. The Resource ID is displayed in the Configuration section.

DB_PERF_INSIGHTS also brings in the DBLoad metric at sub-minute intervals.

Performance Insights metrics retrieved with this function are not stored in CloudWatch. Therefore, some CloudWatch features such as cross-account observability, anomaly detection, metric streams, metrics explorer, and Metric Insights don't work with Performance Insights metrics that you retrieve with DB_PERF_INSIGHTS.

A single request using the DB_PERF_INSIGHTS function can retrieve the following numbers of data points.

  • 1080 data points for high-resolution periods (1s, 10s, 30s)

  • 1440 data points for standard-resolution periods (1m, 5m, 1hr, 1d)

The DB_PERF_INSIGHTS function supports only the following period lengths:

  • 1 second

  • 10 seconds

  • 30 seconds

  • 1 minute

  • 5 minutes

  • 1 hour

  • 1 day

For more information about Amazon RDS Performance Insights counter metrics, see Performance Insights counter metrics.

For more information about Amazon DocumentDB Performance Insights counter metrics, see Performance Insights for counter metrics.

Note

High-resolution metrics with sub-minute granularity retrieved by DB_PERF_INSIGHTS are only applicable to the DBLoad metric, or for operating system metrics if you have enabled Enhanced Monitoring at a higher resolution. For more information about Amazon RDS enhanced monitoring, see Monitoring OS metrics with Enhanced Monitoring.

You can create a high-resolution alarm using the DB_PERF_INSIGHTS function for a maximum time range of three hours. You can use the CloudWatch console to graph metrics retrieved with the DB_PERF_INSIGHTS function for any time range.

DB_PERF_INSIGHTS('RDS', 'db-ABCDEFGHIJKLMNOPQRSTUVWXY1', 'os.cpuUtilization.user.avg')

DB_PERF_INSIGHTS('DOCDB', 'db-ABCDEFGHIJKLMNOPQRSTUVWXY1', ['os.cpuUtilization.idle.avg', 'os.cpuUtilization.user.max'])

DIFF

TS

TS[]

TS

TS[]

Returns the difference between each value in the time series and the preceding value from that time series.

DIFF(m1)

 ✓

DIFF_TIME

TS

TS[]

TS

TS[]

Returns the difference in seconds between the timestamp of each value in the time series and the timestamp of the preceding value from that time series.

DIFF_TIME(METRICS())

 ✓

FILL

TS, [S | REPEAT | LINEAR]

TS[], [TS | S | REPEAT | LINEAR]

TS

TS[]

Fills the missing values of a time series. There are several options for the values to use as the filler for missing values:

  • You can specify a value to use as the filler value.

  • You can specify a metric to use as the filler value.

  • You can use the REPEAT keyword to fill missing values with the most recent actual value of the metric before the missing value.

  • You can use the LINEAR keyword to fill the missing values with values that create a linear interpolation between the values at the beginning and the end of the gap.

Note

When you use this function in an alarm, you can encounter an issue if your metrics are being published with a slight delay, and the most recent minute never has data. In this case, FILL replaces that missing data point with the requested value. That causes the latest data point for the metric to always be the FILL value, which can result in the alarm being stuck in either OK state or ALARM state. You can work around this by using a M out of N alarm. For more information, see Alarm evaluation.

FILL(m1,10)

FILL(METRICS(), 0)

FILL(METRICS(), m1)

FILL(m1, MIN(m1))

FILL(m1, REPEAT)

FILL(METRICS(), LINEAR)

 ✓

FIRST

LAST

TS[]

TS

Returns the first or last time series from an array of time series. This is useful when used with the SORT function. It can also be used to get the high and low thresholds from the ANOMALY_DETECTION_BAND function.

IF(FIRST(SORT(METRICS(), AVG, DESC))>100, 1, 0) Looks at the top metric from an array, which is sorted by AVG. It then returns a 1 or 0 for each data point, depending on whether that data point value is more than 100.

LAST(ANOMALY_DETECTION_BAND(m1)) returns the upper bound of the anomaly prediction band.

 ✓

FLOOR

TS

TS[]

TS

TS[]

Returns the floor of each metric. The floor is the largest integer less than or equal to each value.

FLOOR(m1)

FLOOR(METRICS())

 ✓

IF

IF expression

TS

Use IF along with a comparison operator to filter out data points from a time series, or create a mixed time-series composed of multiple collated time series. For more information, see Using IF expressions.

For examples, see Using IF expressions.

 ✓

INSIGHT_RULE_METRIC

INSIGHT_RULE_METRIC(ruleName, metricName)

TS

Use INSIGHT_RULE_METRIC to extract statistics from a rule in Contributor Insights. For more information, see Graphing metrics generated by rules in CloudWatch.

LAMBDA

LAMBDA(LambdaFunctionName [, optional-arg]*)

TS

TS[]

Calls a Lambda function to query metrics from a data source that is not CloudWatch. For more information, see How to pass arguments to your Lambda function.

LOG

TS

TS[]

TS

TS[]

The LOG of a time series returns the natural logarithm value of each value in the time series.

LOG(METRICS())

 ✓

LOG10

TS

TS[]

TS

TS[]

The LOG10 of a time series returns the base-10 logarithm value of each value in the time series.

LOG10(m1)

 ✓

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.

If you input an array of time series, the MAX function creates and returns a time series that consists of the highest value for each data point, among the time series that were used as the input.

Note

We recommend that you do not use this function in CloudWatch alarms if you want the function to return a scalar. For example, MAX(m2) Whenever an alarm evaluates whether to change state, CloudWatch attempts to retrieve a higher number of data points than the number specified as Evaluation Periods. This function acts differently when extra data is requested.

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

If you input an array of time series, the MIN function creates and returns a time series that consists of the lowest value for each data point, among the time series that were used as the input.

Note

We recommend that you do not use this function in CloudWatch alarms if you want the function to return a scalar. For example, MIN(m2) Whenever an alarm evaluates whether to change state, CloudWatch attempts to retrieve a higher number of data points than the number specified as Evaluation Periods. This function acts differently when extra data is requested.

m1-MIN(m1)

MIN(METRICS())

 ✓

MINUTE

HOUR

DAY

DATE

MONTH

YEAR

EPOCH

TS

TS

These functions take the period and range of the time series and return a new non-sparse time series where each value is based on its timestamp.

  • MINUTE returns a non-sparse time series of integers between 0 and 59 that represent the UTC minute of each timestamp in the original time series.

  • HOUR returns a non-sparse time series of integers between 0 and 23 that represent the UTC hour of each timestamp in the original time series.

  • DAY returns a non-sparse time series of integers between 1 and 7 that represent the UTC day of the week of each timestamp in the original time series. 1 represents Monday and 7 represents Sunday.

  • DATE returns a non-sparse time series of integers between 1 and 31 that represent the UTC day of the month of each timestamp in the original time series.

  • MONTH returns a non-sparse time series of integers between 1 and 12 that represent the UTC month of each timestamp in the original time series. 1 represents January and 12 represents December.

  • YEAR returns a non-sparse time series of integers that represent the UTC year of each timestamp in the original time series.

  • EPOCH returns a non-sparse time series of integers that represent the UTC time in seconds since the Epoch of each timestamp in the original time series. The Epoch is January 1, 1970.

MINUTE(m1)

IF(DAY(m1)<6,m1) returns metrics only from weekdays, Monday to Friday.

IF(MONTH(m1) == 4,m1) returns only metrics published in April.

 ✓

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.

Important

Setting alarms on expressions that use the RATE function on metrics with sparse data can behave unpredictably, because the range of data points fetched when evaluating the alarm can vary based on when the data points were last published.

RATE(m1)

RATE(METRICS())

 ✓

REMOVE_EMPTY

TS[]

TS[]

Removes any time series that have no data points from an array of time series. The result is an array of time series where each time series contains at least one data point.

Note

We recommend that you do not use this function in CloudWatch alarms. Whenever an alarm evaluates whether to change state, CloudWatch attempts to retrieve a higher number of data points than the number specified as Evaluation Periods. This function acts differently when extra data is requested.

REMOVE_EMPTY(METRICS())

✓

RUNNING_SUM

TS

TS[]

TS

TS[]

Returns a time series with the running sum of the values in the original time series.

Note

We recommend that you do not use this function in CloudWatch alarms. Whenever an alarm evaluates whether to change state, CloudWatch attempts to retrieve a higher number of data points than the number specified as Evaluation Periods. This function acts differently when extra data is requested.

RUNNING_SUM([m1,m2])

 ✓

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 Use search expressions in graphs.

You can't create an alarm based on a SEARCH expression. This is because search expressions return multiple time series, and an alarm based on a math expression can watch only one time series.

If you are signed in to a monitoring account in CloudWatch cross-account observability, the SEARCH function finds metrics in the source accounts and the monitoring account.

 ✓

SERVICE_QUOTA

TS that is a usage metric

TS

Returns the service quota for the given usage metric. You can use this to visualize how your current usage compares to the quota, and to set alarms that warn you when you approach the quota. For more information, see AWS usage metrics.

 ✓

SLICE

(TS[], S, S) or (TS[], S)

TS[]

TS