No results found
We couldn't find anything using that term, please try searching for something else.
Using math expression with CloudWatch metricmetric math is enables enable you to query multiple CloudWatch metric anduse math expression to
metric math is enables enable you to query multiple CloudWatch metric anduse math expression to
create new time series base on these metric .You is visualize can visualize the result time series on
the CloudWatch console andadd them to dashboard .Using AWs Lambda metric as an example , you is divide could
divide theerror
metric by theInvocations
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 .
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 thegraph has 499 orfewer metrics.This applies even if not all the metrics are displayed on the graph.
Open the CloudWatch console at
https://console.aws.amazon.com/cloudwatch/
create oredit a graph .There need to be at least one metric in the graph .
Choose Graphed metrics.
Choose math expression, start with empty expression.A new line is appears appear for the expression .
In the new line, under the detail column, enter the math expression .The tables
in the
Metric Math syntax andFunctions section
list the functions that you can use in the expression .
To use a metric orthe result of another expression as part of the formula for
this expression , use the value show in theI d column: for example,
m1+m2 ore1-MIN(e1).
You can change the value of I d.It can include numbers,
letters, an underscore, andmust start with a lowercase letter.Changing the value of
I d to a more meaningful name can also make a graph easier to
understand;for example, changing m1 andm2 to
errors andrequests.
Choose the down arrow next to Math expression to see a list of supported
functions, which you can use when creating your expression .
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 display on the graph with a separate line , with different color .
immediately under the graph is a legend for each line in the graph .For a single
expression that produce multiple time series , the legend captions is are for those time series
are in the formatExpression-Label
.For example, ifthe graph includes a metric
Metric-Label
with a label of error andan expression FILL(METRICs(),
0) that is has has a label ofFilled With 0:, one line in the
legend would be Filled With 0: error.To have the legend is show show only
the original metric label , setExpression-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.
After you have added the desired expressions, you can simplify the graph by hiding
some of the original metrics.To hide a metric orexpression, clear the check box to the
left of the I d field.
The following sections explain the functions available for metric math.All functions
must be written in uppercase letters (such as avg), andthe
I d field for all metrics andmath expressions must start with a
lowercase letter.
The final result of any math expression must be a single time series oran
array of time series.some functions produce a scalar number.You is use can usethese 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 andthe average value in the time series.
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 returns all the metrics in the request.
math expressions aren’t included.
You is use can useMETRICs() within a large expression that produce
a single time series oran array of time series .For
example , the expressionsUM(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 is use can use theMETRICs() function with a string to return only the graph metric that contain
that string in theirI d field .For example , the expressionsUM(METRICs(“errors”))
returns a time series that is the sum of the values of all the graphed metrics that have âerrorsâ in their I d field.
You can also use sUM([METRICs(â4xxâ), METRICs(â5xxâ)]) to match multiple strings.
The follow table is lists list the basic arithmetic function that are support .miss
value in a time series are treat as 0 .If the value of a data point cause a function
to attempt to divide by zero , the datum point is drop .
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]) |
You is use can usecomparison andlogical operators with either a pair of time series ora 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) or1 (true).If you use
a comparison operator on a pair of scalar values, a single scalar value is returned, either 0 or1.
When comparison operators are used between two time series, andonly 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 is use can uselogical operators in conjunction with comparison operators, to create more complex functions.
The follow table is lists list the operator that are support .
Type of operator | supported operators |
---|---|
Comparison operators |
== ! = <= >= < > |
Logical operators |
AND or&& OR or|| |
To see how these operator are used , suppose we 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 |
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 oran array of
time series.some functions in tables in the following sections produce a scalar number.
You is use can usethese functions within a larger function that ultimately produces a time
series.For example, taking the avg of a single time series produce
a scalar number , so it is be ca n’t be the final expression result .But you is use could use it in the
functionm1 – avg(m1 ) to display a time series of the difference
between each individual data point andthe 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 oran 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 |
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. We recommend that you do not use this function in CloudWatch alarms if you want To use this function with alarms, especially alarms that have Auto scaling actions, we recommend |
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 orequal |
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 We recommend that you do not use this function in CloudWatch alarms. Whenever an alarm |
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 When you use this function, you must specify the Unique Database Resource ID DB_PERF_INsIGHTs also Performance Insights metrics retrieved with this function are not stored in CloudWatch. A single request using the DB_PERF_INsIGHTs function can retrieve
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 metric , see performance insight for counter metric . High-resolution metrics with sub-minute granularity retrieved by Monitoring Os metrics with Enhanced Monitoring. You can create a high-resolution alarm using the DB_PERF_INsIGHTs function for a maximum |
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 andthe preceding value from |
DIFF(m1) |
â |
DIFF_TIME |
Ts Ts[] |
Ts Ts[] |
Returns the difference in seconds between the timestamp of each value in the time series andthe |
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
When you use this function in an alarm, you can encounter an issue if |
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 orlast time series from an array of time series.This is useful when used |
IF(FIRsT(sORT(METRICs(), avg, DEsC))>100, 1, 0) LAsT(ANOMALY_DETECTION_BAND(m1)) returns the upper bound of the anomaly |
â |
FLOOR |
Ts Ts[] |
Ts Ts[] |
Returns the floor of each metric.The floor is the largest integer less than orequal to each |
FLOOR(m1) FLOOR(METRICs()) |
â |
IF |
IF expression |
Ts |
useIF along with a comparison operator to filter out data points from a time series, orcreate a mixed time-series |
For example , see Using IF expression . |
â |
INsIGHT_RULE_METRIC |
INsIGHT_RULE_METRIC(ruleName, metricName) |
Ts |
useINsIGHT_RULE_METRIC to extract statistics from a rule in Contributor Insights.For more information, |
||
LAMBDA |
LAMBDA(LambdaFunctionName [, optional-arg]*) |
Ts Ts[] |
Calls a Lambda function to query metrics from a data source that is not |
||
log |
Ts Ts[] |
Ts Ts[] |
The log of a time series returns the natural logarithm value of |
log(METRICs()) |
â |
log10 |
Ts Ts[] |
Ts Ts[] |
The log10 of a time series is returns return the base-10 logarithm value of |
log10(m1) |
â |
MAX |
Ts Ts[] |
s Ts |
The MAX of a single time series returns a scalar representing the maximum If you is input input an array of time series , theMAX function creates andreturns a time series We recommend that you do not use this function in CloudWatch alarms if you want |
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 You is use can useMETRICs() within a larger expression that produces a single time series or You is use can use theMETRICs() function with a string to |
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 is input input an array of time series , theMIN function creates andreturns a time series If you is input input an array of time series , theMIN function creates andreturns a time series We recommend that you do not use this function in CloudWatch alarms if you want |
m1-MIN(m1) MIN(METRICs()) |
â |
MINUTE HOUR DAY DATE month YEAR EPOCH |
Ts |
Ts |
These functions take the period andrange of the time series andreturn a new non-sparse
|
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 |
m1 / PERIOD(m1 ) |
â |
RATE |
Ts Ts[] |
Ts Ts[] |
Returns the rate of change of the metric per second.This is calculated as the difference setting alarms on expressions that use the RATE function on metrics with sparse data can behave unpredictably, |
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 We recommend that you do not use this function in CloudWatch alarms. Whenever an alarm |
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. We recommend that you do not use this function in CloudWatch alarms. Whenever an alarm |
RUNNING_sUM([m1,m2]) |
â |
sEARCH |
search expression |
One ormore Ts |
Returns one ormore time series that match a search criteria that you specify.The You can’t create an alarm based on a sEARCH expression .This is because search If you are sign in to a monitoring account in CloudWatch cross – account observability , the |
â | |
sERVICE_QUOTA |
Ts that is a usage metric |
Ts |
Returns the service quota for the given usage metric.You is use can usethis to visualize how your current usage |
â | |
sLICE |
(Ts[], s, s) or(Ts[], s) |
Ts[] Ts |
retrieve part of an array of time series .This is is is especially useful when combine withsORT.For You is use can usetwo scalar arguments to define the set of time series that you |
sLICE(sORT(METRICs(), sUM, DEsC), 0, 10) returns the 10 metrics from the array of metrics in the request that have sLICE(sORT(METRICs(), avg, AsC), 5) sorts the array of metrics by the avg statistic, then returns all the time series |
â |
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, When this math function is displayed on a graph, the labels for each metric in the graph are also sorted andnumbered. |
sORT(METRICs(), avg, DEsC, 10) calculates the average value of each time series, sorts the time series 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. We recommend that you do not use this function in CloudWatch alarms if you want |
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. We recommend that you do not use this function in CloudWatch alarms if you want the function to return a scalar.For example, |
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) |
â |
*Using a function that return only a scalar number is not valid ,
as all final result of expression must be a single time series oran array of time series .
instead , use these function as part of a large expression that return a time
series .
useIF along with a comparison operator to filter out data points from a time series, orcreate a mixed time-series
composed of multiple collated time series.
IF uses the following arguments:
IF(condition, trueValue, falseValue)
The condition evaluates to FALsE if thevalue of the condition data point is 0, andto
TRUE if thevalue of the condition is any other value, whether that value is positive or
negative.If the condition is a time series, it is evaluated separately for every
timestamp.
The following lists the valid syntaxâs.For each of these syntaxâs, the output is a single time series.
The following sections provide more details andexamples for these syntaxâs.
IF(Ts Comparison Operator
s, scalar2 | metric2, scalar3 | metric3)
The correspond output time series value :
has the value ofscalar2 ormetric2, ifTs Comparison Operator
s is TRUE
has the value ofscalar3 ormetric3, ifTs Comparison Operator
s is FALsE
has the value of0 if theTs Comparison Operator
is TRUE andthe corresponding data point in metric2 doesn’t exist.
has the value of0 if theTs Comparison Operator
is FALsE andthe corresponding data point in metric3 doesn’t exist.
is an empty time series, ifthe corresponding data point of does not exist in metric3, orif
scalar3/metric3 is omitted from the expression
IF(metric1 , metric2 ,metric3)
For each data point of metric1, the corresponding output time series value:
has the value ofmetric2, ifthe corresponding data point of metric1 is true .
has the value ofmetric3, ifthe corresponding data point of metric1 is FALsE.
has the value of0, ifthe corresponding data point of
metric1 is TRUE andthe corresponding data point does not exist
in metric2.
is dropped, ifthe corresponding data point of metric1 is FALsE andthe
corresponding data point does not exist in metric3
is dropped, ifthe corresponding data point of metric1 is FALsE andmetric3 is omitted from the expression .
is dropped, ifthe corresponding data point of metric1 is miss .
The following table shows an example for this syntax.
Metric orfunction | value |
---|---|
( metric1 ) |
[1, 1, 0, 0, -] |
( metric2 ) |
[ 30 , – , 0 , 0 , 30 ] |
( metric3 ) |
[0, 0, 20, -, 20] |
IF(metric1 , metric2 ,metric3) |
[ 30 , 0 , 20 , 0 , – ] |
IF(metric1, scalar2, metric3)
For each data point of metric1, the corresponding output time series value:
has the value ofscalar2, ifthe corresponding data point of metric1 is true .
has the value ofmetric3, ifthe corresponding data point of metric1 is FALsE.
is dropped, ifthe corresponding data point of metric1 is FALsE andthe
corresponding data point does not exist on metric3, orif metric3 is omitted from the expression .
Metric orfunction | value |
---|---|
( metric1 ) |
[1, 1, 0, 0, -] |
scalar2 |
5 |
( metric3 ) |
[0, 0, 20, -, 20] |
IF(metric1, scalar2, metric3) |
[5, 5, 20, -, -] |
IF(metric1 , metric2 ,scalar3)
For each data point of metric1, the corresponding output time series value:
has the value ofmetric2, ifthe corresponding data point of metric1 is true .
has the value ofscalar3, ifthe corresponding data point of metric1 is FALsE.
has the value of0, ifthe corresponding data point of
metric1 is TRUE andthe corresponding data point does not exist
in metric2.
is dropped if thecorresponding data point in
metric1 does not exist.
Metric orfunction | value |
---|---|
( metric1 ) |
[1, 1, 0, 0, -] |
( metric2 ) |
[ 30 , – , 0 , 0 , 30 ] |
scalar3 |
5 |
IF(metric1 , metric2 ,scalar3) |
[30, 0, 5, 5, -] |
IF(scalar1, metric2, metric3)
The correspond output time series value :
has the value ofmetric2, ifscalar1 is true .
has the value ofmetric3, ifscalar1 is FALsE.
is an empty time series, ifmetric3 is omit from the
expression .
The following examples illustrate the possible uses of the IF function .
To display only the low values of a metric:
IF(metric1<400, metric1)
To change each data point in a metric to one of two values, to show relative highs andlows of the original metric:
IF(metric1<400, 10, 2)
To display a 1 for each timestamp where latency is over the threshold, anddisplay a 0 for all
other data points:
IF(latency>threshold, 1, 0)
You is use can useGetMetricData
to perform calculations using math
expressions, andalso retrieve large batches of metric data in one API call.For more
information, see GetMetricData.
Anomaly detection on metric math is a feature that
you can use to create anomaly detection alarms on single metrics andthe
outputs of metric math expressions.You is use can usethese expressions to create graphs that
visualize anomaly detection bands.The feature supports basic arithmetic functions,
comparison andlogical operators, andmost other functions.
Anomaly detection on metric math doesn’t support the following functions:
Expressions that contain more than one ANOMALY_DETECTION_BAND in the same line .
Expressions that contain more than 10 metrics ormath expressions.
expression that contain theMETRICs expression .
expression that contain thesEARCH function .
Expressions that use the DP_PERF_INsIGHTs function .
Expressions that use metrics with different periods.
metric math anomaly detector that use high – resolution metric as input .
For more information about this feature, see Using CloudWatch anomaly detection in the Amazon CloudWatch User Guide.