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