1 Aggregate functions

Except where stated otherwise, all functions listed here are supported in:

Aggregate functions can work with either:

  • history of items, for example, min(/host/key,1h)
  • foreach functions as the only parameter, for example, min(last_foreach(/*/key)) (only in calculated items; cannot be used in triggers)

Some general notes on function parameters:

  • Function parameters are separated by a comma
  • Optional function parameters (or parameter parts) are indicated by < >
  • Function-specific parameters are described with each function
  • /host/key and (sec|#num)<:time shift> parameters must never be quoted
Common parameters
  • /host/key is a common mandatory first parameter for the functions referencing the host item history
  • (sec|#num)<:time shift> is a common second parameter for the functions referencing the host item history, where:
    • sec - maximum evaluation period in seconds (time suffixes can be used), or
    • #num - maximum evaluation range in latest collected values (if preceded by a hash mark)
    • time shift (optional) allows to move the evaluation point back in time. See more details on specifying time shift.

Aggregate functions

FUNCTION
Description Function-specific parameters Comments
avg (/host/key,(sec|#num)<:time shift>)
Average value of an item within the defined evaluation period. See common parameters. Supported value types: float, int

Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach

Examples:
=> avg(/host/key,1h) → average value for the last hour until now
=> avg(/host/key,1h:now-1d) → average value for an hour from 25 hours ago to 24 hours ago from now
=> avg(/host/key,#5) → average value of the five latest values
=> avg(/host/key,#5:now-1d) → average value of the five latest values excluding the values received in the last 24 hours

Time shift is useful when there is a need to compare the current average value with the average value some time ago.
bucket_percentile (item filter,time period,percentage)
Calculates the percentile from the buckets of a histogram. item filter - see item filter
time period - see time period
percentage - percentage (0-100)
Supported only in calculated items.

This function is an alias for histogram_quantile(percentage/100, bucket_rate_foreach(item filter, time period, 1))
count (func_foreach(item filter,<time period>))
Count of values in an array returned by a foreach function. func_foreach - foreach function for which the number of returned values should be counted (with supported arguments). See foreach functions for details. Supported value type: int

Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach

Example:
=> count(max_foreach(/*/net.if.in[*],1h)) → number of net.if.in items that received data in the last hour until now

Note that using count() with a history-related foreach function (max_foreach, avg_foreach, etc.) may lead to performance implications, whereas using exists_foreach(), which works only with configuration data, will not have such effect.
histogram_quantile (quantile,bucket1,value1,bucket2,value2,...)
Calculates the φ-quantile from the buckets of a histogram. quantile - 0 ≤ φ ≤ 1
bucketN, valueN - manually entered pairs (>=2) of parameters or response of bucket_rate_foreach
Supported only in calculated items.

Supported foreach functions: bucket_rate_foreach

Functionally corresponds to 'histogram_quantile' of PromQL.

Returns -1 if values of the last 'Infinity' bucket ("+inf") are equal to 0.

Examples:
=> histogram_quantile(0.75,1.0,last(/host/rate_bucket[1.0]),"+Inf",last(/host/rate_bucket[Inf])
=> histogram_quantile(0.5,bucket_rate_foreach(//item_key,30s))
item_count (item filter)
Count of existing items in configuration that match filter criteria. item filter - criteria for item selection, allows referencing by host group, host, item key, and tags. Wildcards are supported. See item filter for more details. Supported only in calculated items.

Supported value type: int

Works as an alias for the count(exists_foreach(item_filter)) function.

Example:
=> item_count(/*/agent.ping?[group="Host group 1"]) → number of hosts with the agent.ping item in the "Host group 1"
kurtosis (/host/key,(sec|#num)<:time shift>)
"Tailedness" of the probability distribution in collected values within the defined evaluation period.

See also: Kurtosis
See common parameters. Supported value types: float, int

Supported foreach functions: last_foreach

Example:
=> kurtosis(/host/key,1h) → kurtosis for the last hour until now
mad (/host/key,(sec|#num)<:time shift>)
Median absolute deviation in collected values within the defined evaluation period.

See also: Median absolute deviation
See common-parameters. Supported value types: float, int

Supported foreach functions: last_foreach

Example:
=> mad(/host/key,1h) → median absolute deviation for the last hour until now
max (/host/key,(sec|#num)<:time shift>)
Highest value of an item within the defined evaluation period. See common parameters. Supported value types: float, int

Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach

Example:
=> max(/host/key,1h) - min(/host/key,1h) → calculate the difference between the maximum and minimum values within the last hour until now (delta of values)
min (/host/key,(sec|#num)<:time shift>)
Lowest value of an item within the defined evaluation period. See common parameters. Supported value types: float, int

Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach

Example:
=> max(/host/key,1h) - min(/host/key,1h) → calculate the difference between the maximum and minimum values within the last hour until now (delta of values)
skewness (/host/key,(sec|#num)<:time shift>)
Asymmetry of the probability distribution in collected values within the defined evaluation period.

See also: Skewness
See common parameters. Supported value types: float, int

Supported foreach functions: last_foreach

Example:
=> skewness(/host/key,1h) → skewness for the last hour until now
stddevpop (/host/key,(sec|#num)<:time shift>)
Population standard deviation in collected values within the defined evaluation period.

See also: Standard deviation
See common parameters. Supported value types: float, int

Supported foreach functions: last_foreach

Example:
=> stddevpop(/host/key,1h) → population standard deviation for the last hour until now
stddevsamp (/host/key,(sec|#num)<:time shift>)
Sample standard deviation in collected values within the defined evaluation period.

See also: Standard deviation
See common parameters. Supported value types: float, int

Supported foreach functions: last_foreach

At least two data values are required for this function to work.

Example:
=> stddevsamp(/host/key,1h) → sample standard deviation for the last hour until now
sum (/host/key,(sec|#num)<:time shift>)
Sum of collected values within the defined evaluation period. See common parameters. Supported value types: float, int

Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach

Example:
=> sum(/host/key,1h) → sum of values for the last hour until now
sumofsquares (/host/key,(sec|#num)<:time shift>)
The sum of squares in collected values within the defined evaluation period. See common parameters. Supported value types: float, int

Supported foreach functions: last_foreach

Example:
=> sumofsquares(/host/key,1h) → sum of squares for the last hour until now
varpop (/host/key,(sec|#num)<:time shift>)
Population variance of collected values within the defined evaluation period.

See also: Variance
See common parameters. Supported value types: float, int

Supported foreach functions: last_foreach

Example:
=> varpop(/host/key,1h) → population variance for the last hour until now
varsamp (/host/key,(sec|#num)<:time shift>)
Sample variance of collected values within the defined evaluation period.

See also: Variance
See common parameters. Supported value types: float, int

Supported foreach functions: last_foreach

At least two data values are required for this function to work.

Example:
=> varsamp(/host/key,1h) → sample variance for the last hour until now