Documentation
1 循环处理函数
概述
Foreach函数在aggregate calculations中用于为每一个被使用的监控项过滤器选中的监控项返回一个聚合值。该函数返回一个值的array。
例如，avg_foreach函数将返回一个值的array，其中每个值是在指定时间间隔内所选监控项的平均历史值。
监控项过滤器是foreach函数所使用语法的一部分。
在监控项过滤器中支持通配符的使用，因此可以非常灵活地选择所需的监控项。
支持函数
| 函数 | 描述 |
|---|---|
| avg_foreach | 返回每个监控项的平均值。 |
| bucket_rate_foreach | 返回适用于histogram_quantile()函数的（桶上限，速率值）对，其中"桶上限"是由<参数编号>参数定义的监控项键参数值。 |
| count_foreach | 返回每个监控项的数值数量。 |
| exists_foreach | 为每个启用的监控项返回'1'。 |
| last_foreach | 返回每个监控项的最后一个值。 |
| max_foreach | 返回每个监控项的最大值。 |
| min_foreach | 返回每个监控项的最小值。 |
| sum_foreach | 返回每个监控项的数值总和。 |
函数语法
Foreach 函数支持两个通用参数：item filter（详见下文）和 time period：
例如：
avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)
将返回 MySQL 服务器组中每个 'mysql.qps' 监控项 的五分钟平均值。
请注意，某些函数支持额外的参数。
监控项 过滤器语法
监控项过滤器：
包含四个部分，其中：
- 主机 - 主机名
- key - 监控项 键（不带参数）
- 参数 - 监控项 键参数
- conditions - 基于主机组和/或监控项标签的条件（作为表达式）
条件表达式中仅允许在内部使用空格。
通配符用法
- 通配符可用于替换主机名称、监控项键或单个监控项键参数。
- 必须指定不含通配符的主机或监控项键。因此
/host/*和/*/key是有效过滤器，但/*/*无效。 - 通配符不能用于主机名的部分、监控项键或监控项键参数。
- 通配符不能匹配多个监控项键参数。因此必须为每个参数单独指定通配符（即
key[abc,*,*]）。
条件表达式
条件表达式支持：
- 操作数：
- group - 主机组
- tag - 监控项 tag
"<text>"- string常量，使用\转义字符来转义"和\
- 区分大小写 string 的比较运算符：
=、<> - 逻辑运算符：
and、or、not - 使用括号分组：
()
引用string常量时必须使用引号。仅支持区分大小写的完整string比对。
在过滤器中指定标签时（即tag="tagname:value"），冒号":"用作分隔符。 冒号后的所有内容均被视为标签值。因此，当前不支持在标签名称中包含":"。
示例
可以使用一个复杂过滤器，引用监控项键、主机组和标签，如示例所示：
| 语法示例 | 说明 |
|---|---|
/host/key[abc,*] |
匹配此主机上的类似监控项。 |
/*/key |
匹配任意主机的相同监控项。 |
/*/key?[group="ABC" and tag="tagname:value"] |
匹配ABC组中任何具有'tagname:value'标签的监控项的相同主机。 |
/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] |
匹配来自ABC或DEF组的任意监控项的相似主机，并附带相应标签。 |
所有引用的监控项必须存在并收集数据。 仅启用的监控项在启用的主机上会被纳入计算。 处于不支持状态的监控项不包含在内。
如果引用的监控项的监控项键被更改，则必须手动更新过滤器。
指定父级主机组将包含父组及其所有嵌套的主机组及其监控项。
时间段
第二个参数允许指定聚合的时间周期。
时间周期只能以时间形式表示，不支持使用值的数量（以#开头的形式）。
此参数中可以使用Supported unit symbols以方便表示时间周期，
例如，使用'5m'（5分钟）代替'300s'（300秒），或使用'1d'（1天）代替'86400'（86400秒）。
对于last_foreach函数，时间周期是一个可选参数（自Zabbix 7.0起支持），可以省略：
exists_foreach函数不支持使用时间周期。
附加参数
bucket_rate_foreach
bucket_rate_foreach 函数支持第三个可选参数：
其中 <parameter number> 是 监控项 键中 "bucket" 值的位置。
例如，如果 myItem[aaa,0.2] 中的 "bucket" 值是 '0.2'，那么它的位置是 2。
<parameter number> 的默认值是 '1'。
count_foreach
count_foreach 函数支持第三和第四个可选参数：
其中：
- operator 是 监控项值 的条件运算符（必须用双引号括起）。支持的
operators有：
eq - 等于
ne - 不等于
gt - 大于
ge - 大于或等于
lt - 小于
le - 小于或等于
like - 包含模式匹配（区分大小写）
bitand - 按位与
regexp - 对pattern中提供的正则表达式进行区分大小写的匹配
iregexp - 对pattern中提供的正则表达式进行不区分大小写的匹配 - pattern 是所需的模式（string 参数必须用双引号括起）；如果在第三个参数中指定了 operator，则支持该参数。
备注：
- 可选参数 operator 或 pattern 在逗号之后不能留空，只能完全省略。
- 当第三个参数为 bitand 时，第四个
pattern参数可以指定为两个数字，用 '/' 分隔：number_to_compare_with/mask。count_foreach() 会从值和 mask 计算 "按位与"，并将结果与 number_to_compare_with 进行比较。如果 "按位与" 的结果等于 number_to_compare_with，则该值会被计数。
如果 number_to_compare_with 和 mask 相等，则只需指定 mask（不带 '/'）。 - 当第三个参数为 regexp 或 iregexp 时，第四个
pattern参数可以是普通正则表达式或 全局正则表达式（以 '@' 开头）。对于全局正则表达式，其区分大小写特性继承自全局正则表达式设置。为了进行正则匹配，float 值始终以 4 小数点后四位数字表示。同时请注意，对于大数字，十进制（存储在数据库中）和二进制（由 Zabbix server 使用）表示之间的差异可能会影响第四位小数。
更多关于使用 foreach 函数的详细信息和示例，请参见 aggregate calculations。
根据可用性的行为表现
下表说明了每个函数在主机/监控项和历史数据可用性受限时的行为。
| 函数 | 已禁用 主机 | 数据存在时主机不可用 | 数据不存在时主机不可用 | 已禁用 监控项 | 不支持 监控项 | 数据检索错误（SQL） |
|---|---|---|---|---|---|---|
| avg_foreach | 忽略 | 返回平均值 | 忽略 | 忽略 | 忽略 | 忽略 |
| bucket_rate_foreach | 忽略 | 返回桶速率 | 忽略 | 忽略 | 忽略 | 忽略 |
| count_foreach | 忽略 | 返回计数 | 0 | 忽略 | 忽略 | 忽略 |
| exists_foreach | 忽略 | 1 | 1 | 忽略 | 1 | 不适用 |
| last_foreach | 忽略 | 返回最新值 | 忽略 | 忽略 | 忽略 | 忽略 |
| max_foreach | 忽略 | 返回最大值 | 忽略 | 忽略 | 忽略 | 忽略 |
| min_foreach | 忽略 | 返回最小值 | 忽略 | 忽略 | 忽略 | 忽略 |
| sum_foreach | 忽略 | 返回总和 | 忽略 | 忽略 | 忽略 | 忽略 |
如果监控项被忽略，则不会向聚合中添加任何内容。