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