Using math expressions with CloudWatch metrics

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

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.

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.

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.

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.

The DB_PERF_INSIGHTS function supports only the following period lengths:

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.

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:

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.

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.

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.

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

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.

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.

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

Retrieves part of an array of time series. This is especially useful when combined with SORT. For example, you can exclude the top result from an array of time series.

You can use two scalar arguments to define the set of time series that you want returned. The two scalars define the start (inclusive) and end (exclusive) of the array to return. The array is zero-indexed, so the first time series in the array is time series 0. Alternatively, you can specify just one value, and CloudWatch returns all time series starting with that value.

SLICE(SORT(METRICS(), SUM, DESC), 0, 10) returns the 10 metrics from the array of metrics in the request that have the highest SUM value.

SLICE(SORT(METRICS(), AVG, ASC), 5) sorts the array of metrics by the AVG statistic, then returns all the time series except for the 5 with the lowest AVG.

SORT

(TS[], FUNCTION, SORT_ORDER)

(TS[], FUNCTION, SORT_ORDER, S)

TS[]

Sorts an array of time series according to the function you specify. The function you use can be AVG, MIN, MAX, or SUM. The sort order can be either ASC for ascending (lowest values first) or DESC to sort the higher values first. You can optionally specify a number after the sort order which acts as a limit. For example, specifying a limit of 5 returns only the top 5 time series from the sort.

When this math function is displayed on a graph, the labels for each metric in the graph are also sorted and numbered.

SORT(METRICS(), AVG, DESC, 10) calculates the average value of each time series, sorts the time series with the highest values at the beginning of the sort, and returns only the 10 time series with the highest averages.

SORT(METRICS(), MAX, ASC) sorts the array of metrics by the MAX statistic, then returns all of them in ascending order.

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

TIME_SERIES

S

TS

Returns a non-sparse time series where every value is set to a scalar argument.

TIME_SERIES(MAX(m1))

TIME_SERIES(5*AVG(m1))

TIME_SERIES(10)