Foreach 函数

概述

Foreach 函数用于聚合计算，为所使用的监控项过滤器所选中的每个监控项返回一个聚合值。返回结果是一个值数组。

例如，avg_foreach 函数将返回一个值数组，其中每个值都是所选监控项在指定时间间隔内的平均历史值。

item 过滤器是 foreach 函数所用语法的一部分。 item 过滤器支持使用通配符，因此可以非常灵活地选择所需的监控项。

支持的函数

函数语法

Foreach 函数支持两个通用参数：监控项过滤器（详见下文）和 时间周期：

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 - 基于主机组和/或监控项标签的条件（以表达式形式）

仅允许在 conditions 表达式内部使用空格。

通配符用法

• 可使用通配符替代主机名称、监控项键值或单个监控项键值参数。
• host 或 key 中必须有一项是不使用通配符明确指定的。因此，/host/* 和 /*/key 是有效过滤器，而 /*/* 无效。
• 通配符不能用于主机名称、监控项键值或监控项键值参数的一部分。
• 通配符不能匹配多个监控项键值参数。因此，必须分别为每个参数单独指定通配符（即 key[abc,*,*]）。

条件表达式

conditions 表达式支持：

• 操作数：
  • group - 主机组
  • tag - 监控项标签
  • "<text>" - 字符串常量，使用转义字符 \ 对 " 和 \ 进行转义
• 区分大小写的字符串比较运算符：=, <>
• 逻辑运算符：and, or, not
• 使用括号分组：( )

字符串常量必须使用引号。仅支持区分大小写的完整字符串比较。

示例

可使用复杂过滤器来引用监控项键值、主机组和标签，如下例所示：

所有被引用的监控项都必须存在并采集数据。
只有已启用主机上的已启用监控项才会被纳入计算。
处于不支持状态的监控项不会被纳入。

指定父主机组时，将包含该父组及其所有嵌套主机组中的监控项。

时间周期

第二个参数用于指定聚合的时间周期。 时间周期只能以时间形式表示，不支持值的数量（以 # 为前缀）。

为方便起见，此参数中可以使用支持的单位符号， 例如，使用“5m”（五分钟）代替“300s”（300 秒），或使用“1d”（一天）代替“86400”（86400 秒）。

对于 last_foreach 函数，时间周期是一个可选参数（自 Zabbix 7.0 起支持），可以省略：

last_foreach(/*/key?[group="host group"])

time period 不支持与 exists_foreach 函数一起使用。

附加参数

bucket_rate_foreach

bucket_rate_foreach 函数支持第三个可选参数：

bucket_rate_foreach(item filter,time period,<parameter number>)

其中，<parameter number> 是监控项键中“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 是用于监控项值的条件运算符（必须用双引号括起来）。支持的 operators：
  eq - 等于
  ne - 不等于
  gt - 大于
  ge - 大于或等于
  lt - 小于
  le - 小于或等于
  like - 包含模式时匹配（区分大小写）
  bitand - 按位与
  regexp - 对 pattern 中给定的正则表达式进行区分大小写的匹配
  iregexp - 对 pattern 中给定的正则表达式进行不区分大小写的匹配
  
• pattern 是必需的模式（字符串参数必须用双引号括起来）；当第三个参数中指定了 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 参数可以是普通正则表达式或全局（以“@”开头）正则表达式。对于全局正则表达式，大小写敏感性继承自全局正则表达式设置。出于正则表达式匹配的目的，浮点值始终会以小数点后 4 位小数的形式表示。另请注意，对于大数字，十进制（存储在数据库中）和二进制（由 Zabbix 服务器使用）表示方式之间的差异可能会影响第 4 位小数。

有关使用 foreach 函数的更多详细信息和示例，请参见聚合计算。

取决于可用性的行为

下表说明了在主机/监控项以及历史数据可用性受限的情况下，各个函数的行为方式。

如果监控项被忽略，则不会向聚合中添加任何内容。