Table of Contents
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/keyand(sec|#num)<:time shift>parameters must never be quoted
Common parameters
/host/keyis 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 |