This is a translation of the original English documentation page. Help us make it better.

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

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

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

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.

Functionally corresponds to 'histogram_quantile' of PromQL.

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

Example:
=> 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 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

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

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

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

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

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

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

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

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

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

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

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