filter Metrics Operator

You can use the filter operator to limit the results returned by a metric query. There are several ways you can restrict results. You can apply an aggregation function, such as avg, to a time series. You can also filter based on how many times the value of individual data points meet a value condition over a particular duration.

filter Syntax

There are two supported syntaxes for the filter operator.

Syntax 1

The first variant filters based on a function (usually an aggregation function) applied to the time series.

metric query | filter [REDUCER BOOLEAN EXPRESSION]

Where:

[REDUCER BOOLEAN EXPRESSION] is an expression that takes all the values of a given time series, uses a function to reduce them to a single value, and evaluates that value. 

The supported functions are:

• avg. Returns the average of the time series.
• min. Returns the minimum value in the time series.
• max. Returns the maximum value in the time series.
• sum. Returns the sum of the values in the time series.
• count. Returns the count of data points in the time series.
• pct(n). Returns the nth percentile of the values in the time series.
• latest. Returns the last data point in the time series.

Syntax 1 examples

Example 1

Return the time series in which the average value of the CPU_User metric is greater than 95:

metric=CPU_User | filter avg > 95

Example 2

Return the time series in which the latest value of the CPU_User metric is greater than 50:

metric=CPU_User | filter latest > 50

Syntax 2

The second variant filters based on how many times the values of individual data points of a time series meet a value condition over a particular duration.

SELECTOR | filter _value [VALUE BOOLEAN EXPRESSION] [all | atleast n] [first | any | last] [duration]

Where:

• [VALUE BOOLEAN EXPRESSION] is a value expression that operates on individual data points of a time series. For example, > 3
• Use all to specify that all data points within the duration must meet the value condition, or atleast n, where n is a count, to specify how many data points must meet the value condition.
• Use first, any, or last to specify what part of the time range that duration applies to: the start of the time range, any part of the time range, or the end of the time range.
• Use duration to specify the length of time to consider in the query in minutes (m), hours (h), or days (d). For example, 5m, 6h, or 1d.

Syntax 2 examples

Example 1

Return only the time series in which all data points during the last 5 minutes of the query time range have a value greater than 3. 

note

There must be a least one data point in the last 5 minutes of the time range for this to be valid.

filter _value > 3 all last 5m

Example 2

Return only the time series that have at least 1 data point greater than 3 for the last 5 minutes of the query time range. 

filter _value > 3 atleast 1 last 5m

Example 3

Return only the time series that have only values greater than 3 for any consecutive 5 minutes of the time range.

filter _value > 3 all any 5m

Example 4

Return only the time series that have only values greater than 3 for the first 5 minutes of the query time range. 

tip

There must be a least one data point in the first 5 minutes of the time range for this to be valid.

filter _value > 3 all first 5m