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)

The functions are listed without additional information. Click on the function to see the full details.

Function Description
avg The average value of an item within the defined evaluation period.
bucket_percentile Calculates the percentile from the buckets of a histogram.
count The count of values in an array returned by a foreach function.
histogram_quantile Calculates the φ-quantile from the buckets of a histogram.
item_count The count of existing items in configuration that match the filter criteria.
kurtosis The "tailedness" of the probability distribution in collected values within the defined evaluation period.
mad The median absolute deviation in collected values within the defined evaluation period.
max The highest value of an item within the defined evaluation period.
min The lowest value of an item within the defined evaluation period.
skewness The asymmetry of the probability distribution in collected values within the defined evaluation period.
stddevpop The population standard deviation in collected values within the defined evaluation period.
stddevsamp The sample standard deviation in collected values within the defined evaluation period.
sum The sum of collected values within the defined evaluation period.
sumofsquares The sum of squares in collected values within the defined evaluation period.
varpop The population variance of collected values within the defined evaluation period.
varsamp The sample variance of collected values within the defined evaluation period.

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.

Function details

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
avg(/host/key,(sec|#num)<:time shift>)

The average value of an item within the defined evaluation period.
Supported value types: Float, Integer.
Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach.

Parameters: see common parameters.

Time shift is useful when there is a need to compare the current average value with the average value some time ago.

Examples:

avg(/host/key,1h) #the average value for the last hour until now
       avg(/host/key,1h:now-1d) #the average value for an hour from 25 hours ago to 24 hours ago from now
       avg(/host/key,#5) #the average value of the five latest values
       avg(/host/key,#5:now-1d) #the average value of the five latest values excluding the values received in the last 24 hours
bucket_percentile(item filter,time period,percentage)

Calculates the percentile from the buckets of a histogram.

Parameters:

Comments:

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

The count of values in an array returned by a foreach function.
Supported value type: Integer.
Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach.

Parameters:

  • func_foreach - foreach function for which the number of returned values should be counted (with supported arguments). See foreach functions for details.
  • item filter - see item filter;
  • time period - see time period.

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.

Examples:

count(max_foreach(/*/net.if.in[*],1h)) #the number of net.if.in items that received data in the last hour until now
histogram_quantile(quantile,bucket1,value1,bucket2,value2,...)

Calculates the φ-quantile from the buckets of a histogram.
Supported foreach function: bucket_rate_foreach.

Parameters:

  • quantile - 0 ≤ φ ≤ 1;
  • bucketN, valueN - manually entered pairs (>=2) of parameters or the response of bucket_rate_foreach.

Comments:

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

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)

The count of existing items in configuration that match the filter criteria.
Supported value type: Integer.

Parameter:

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

Comments:

  • Supported only in calculated items;
  • Works as an alias for the count(exists_foreach(item_filter)) function.

Examples:

item_count(/*/agent.ping?[group="Host group 1"]) #the number of hosts with the *agent.ping* item in the "Host group 1"
kurtosis(/host/key,(sec|#num)<:time shift>)

The "tailedness" of the probability distribution in collected values within the defined evaluation period. See also: Kurtosis.
Supported value types: Float, Integer.
Supported foreach function: last_foreach.

Parameters: see common parameters.

Example:

kurtosis(/host/key,1h) #kurtosis for the last hour until now
mad(/host/key,(sec|#num)<:time shift>)

The median absolute deviation in collected values within the defined evaluation period. See also: Median absolute deviation.
Supported value types: Float, Integer.
Supported foreach function: last_foreach.

Parameters: see common parameters.

Example:

mad(/host/key,1h) #median absolute deviation for the last hour until now
max(/host/key,(sec|#num)<:time shift>)

The highest value of an item within the defined evaluation period.
Supported value types: Float, Integer.
Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach.

Parameters: see common parameters.

Example:

max(/host/key,1h) - min(/host/key,1h) #calculate the difference between the maximum and minimum values within the last hour until now (the delta of values)
min(/host/key,(sec|#num)<:time shift>)

The lowest value of an item within the defined evaluation period.
Supported value types: Float, Integer.
Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach.

Parameters: see common parameters.

Example:

max(/host/key,1h) - min(/host/key,1h) #calculate the difference between the maximum and minimum values within the last hour until now (the delta of values)
skewness(/host/key,(sec|#num)<:time shift>)

The asymmetry of the probability distribution in collected values within the defined evaluation period. See also: Skewness.
Supported value types: Float, Integer.
Supported foreach function: last_foreach.

Parameters: see common parameters.

Example:

skewness(/host/key,1h) #the skewness for the last hour until now
stddevpop(/host/key,(sec|#num)<:time shift>)

The population standard deviation in collected values within the defined evaluation period. See also: Standard deviation.
Supported value types: Float, Integer.
Supported foreach function: last_foreach.

Parameters: see common parameters.

Example:

stddevpop(/host/key,1h) #the population standard deviation for the last hour until now
stddevsamp(/host/key,(sec|#num)<:time shift>)

The sample standard deviation in collected values within the defined evaluation period. See also: Standard deviation.
Supported value types: Float, Integer.
Supported foreach function: last_foreach.

Parameters: see common parameters.

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

Example:

stddevsamp(/host/key,1h) #the sample standard deviation for the last hour until now
sum(/host/key,(sec|#num)<:time shift>)

The sum of collected values within the defined evaluation period.
Supported value types: Float, Integer.
Supported foreach functions: avg_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach.

Parameters: see common parameters.

Example:

sum(/host/key,1h) #the 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.
Supported value types: Float, Integer.
Supported foreach function: last_foreach.

Parameters: see common parameters.

Example:

sumofsquares(/host/key,1h) #the sum of squares for the last hour until now
varpop(/host/key,(sec|#num)<:time shift>)

The population variance of collected values within the defined evaluation period. See also: Variance.
Supported value types: Float, Integer.
Supported foreach function: last_foreach.

Parameters: see common parameters.

Example:

varpop(/host/key,1h) #the population variance for the last hour until now
varsamp(/host/key,(sec|#num)<:time shift>)

The sample variance of collected values within the defined evaluation period. See also: Variance.
Supported value types: Float, Integer.
Supported foreach function: last_foreach.

Parameters: see common parameters.

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

Example:

varsamp(/host/key,1h) #the sample variance for the last hour until now

See all supported functions.