1 Aggregate functions

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

• Trigger expressions
• Calculated items
• Expression macros

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.

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:

• item filter - see item filter;
  
• time period - see time period;
  
• percentage - percentage (0-100).

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>),<operator>,<pattern>)

The count of values in an array returned by a foreach function.
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. See foreach functions for details. Note that count_foreach and bucket_rate_foreach support additional parameters.
• item filter - see item filter;
  
• time period - see time period;
  
• operator (must be double-quoted). Supported operators:
  eq - equal
  ne - not equal
  gt - greater
  ge - greater or equal
  lt - less
  le - less or equal
  like - matches if contains pattern (case-sensitive)
  bitand - bitwise AND
  regexp - case-sensitive match of the regular expression given in pattern
  iregexp - case-insensitive match of the regular expression given in pattern
  
• pattern - the required pattern (string arguments must be double-quoted); supported if operator is specified in the third parameter.

Comments:

• 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.
• Optional parameters operator or pattern can't be left empty after a comma, only fully omitted.
• With bitand as the third parameter, the fourth pattern parameter can be specified as two numbers, separated by '/': number_to_compare_with/mask. count() calculates "bitwise AND" from the value and the mask and compares the result to number_to_compare_with. If the result of "bitwise AND" is equal to number_to_compare_with, the value is counted.
  If number_to_compare_with and mask are equal, only the mask need be specified (without '/').
• With regexp or iregexp as the third parameter, the fourth pattern parameter can be an ordinary or global (starting with '@') regular expression. In case of global regular expressions case sensitivity is inherited from global regular expression settings. For the purpose of regexp matching, float values will always be represented with 4 decimal digits after '.'. Also note that for large numbers difference in decimal (stored in database) and binary (used by Zabbix server) representation may affect the 4th decimal digit.

Examples:

count(max_foreach(/*/net.if.in[*],1h)) #the number of net.if.in items that received data in the last hour until now
count(last_foreach(/*/vfs.fs.size[*,pused]),"gt",95) #the number of file systems with over 95% of disk space used

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.