Foreach functions are used in aggregate calculations to return one aggregate value for each item that is selected by the used item filter.
For example, the avg_foreach function will return the average value from the history of each selected item, during the time interval that is specified.
The item filter is part of the syntax used by foreach functions. The use of wildcards is supported in the item filter, thus the required items can be selected quite flexibly.
|avg_foreach||Returns the average value for each item.|
|bucket_rate_foreach||Returns pairs (bucket upper bound, rate value) suitable for use in the histogram_quantile() function, where "bucket upper bound" is the value of item key parameter defined by the <parameter number> parameter.|
|count_foreach||Returns the number of values for each item.|
|exists_foreach||Returns the number of currently enabled items.|
|last_foreach||Returns the last value for each item.|
|max_foreach||Returns the maximum value for each item.|
|min_foreach||Returns the minimum value for each item.|
|sum_foreach||Returns the sum of values for each item.|
Foreach functions support two common parameters:
item filter (see details below) and
will return the five-minute average of each 'mysql.qps' item in the MySQL server group.
Note that some functions support additional parameters.
The item filter:
consists of four parts, where:
Spaces are allowed only inside the conditions expression.
/*/keyare valid filters, but
The conditions expression supports:
"<text>"- string constant, with the
\escape character to escape
Quotation of string constants is mandatory. Only case-sensitive full string comparison is supported.
A complex filter may be used, referencing the item key, host group and tags, as illustrated by the examples:
||Matches similar items on this host.|
||Matches the same item of any host.|
||Matches the same item of any host from the ABC group having 'tagname:value' tags.|
||Matches similar items of any host from the ABC or DEF group with the respective tags.|
All referenced items must exist and collect data. Only enabled items on enabled hosts are included in the calculations. Items in the unsupported state are not included.
If the item key of a referenced item is changed, the filter must be updated manually.
Specifying a parent host group includes the parent group and all nested host groups with their items.
The second parameter allows to specify the time period for aggregation. The time period can only be expressed as time, the amount of values (prefixed with #) is not supported.
Supported unit symbols can be used in this parameter for convenience, for example, '5m' (five minutes) instead of '300s' (300 seconds) or '1d' (one day) instead of '86400' (86400 seconds).
For the last_foreach function time period is an optional parameter (supported since Zabbix 7.0), which can be omitted:
Time period is not supported with the exists_foreach function.
A third optional parameter is supported by the bucket_rate_foreach function:
where <parameter number> is the position of the "bucket" value in the item key. For example, if the "bucket" value in myItem[aaa,0.2] is '0.2', then its position is 2.
The default value of <parameter number> is '1'.
Third and fourth optional parameters are supported by the count_foreach function:
patternparameter 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.
patternparameter 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.
See aggregate calculations for more details and examples on using foreach functions.