1 循环处理函数

概述

Foreach函数在aggregate calculations中用于为每一个被使用的监控项过滤器选中的监控项返回一个聚合值。该函数返回一个值的array。

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

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

{HEADER_29427838}

函数语法

Foreach 函数支持两个通用参数：item filter（详见下文）和 time period：

foreach_function(监控项 filter, time period)

例如：

avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)

将返回 MySQL 服务器组中每个 'mysql.qps' 监控项 的五分钟平均值。

请注意，某些函数支持额外的参数。

监控项 过滤器语法

监控项过滤器：

`/主机/key[parameters]?[conditions]`

由四个部分组成，其中：

• 主机 - 主机名
• 密钥 - 监控项 密钥（不带参数）
• 参数 - 监控项 键参数
• 条件 - 主机组 和/或 监控项 标签基于条件（作为表达式）

条件表达式内部才允许使用空格。

通配符使用

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

条件表达式

条件表达式支持：

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

引用 string 常量是强制性的。仅支持区分大小写的完整 string 比较。

:::notewarning 在过滤器中指定标签时（即 tag="tagname:value"），使用冒号 ":" 作为分隔符。 冒号后面的所有内容都被视为标签值。因此，目前不支持在标签名称中包含“:”的情况。 仅返回OutputFormat格式要求结果

示例

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

仅返回OutputFormat格式要求结果 | /host/key[abc,*] | 匹配此 主机 上类似的 监控项。 | | /*/key | 匹配任意 主机 的相同 监控项。 | | /*/key?[group="ABC" and tag="tagname:value"] | 匹配具有 'tagname:value' 标签的 ABC 组中任何 主机 的相同 监控项。 | | /*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] | 匹配来自ABC或DEF组中具有相应标签的任何主机的类似监控项。 | 所有引用的 监控项 必须存在并且收集数据。 仅启用的 监控项 在启用的 主机 上才会包含在计算中。 处于不支持状态的监控项未包含在内。

::: noteimportant 如果引用的 监控项 的 监控项 键发生更改，则必须手动更新筛选器。 仅返回OutputFormat格式要求结果

指定父级 主机组 将包括父级组及其所有嵌套的 主机 组及其 监控项。

时间段

第二个参数允许指定聚合的时间周期。
时间周期只能以时间形式表示，不支持使用值的数量（以#开头的形式）。

此参数中可以使用Supported unit symbols以方便表示时间周期，
例如，使用'5m'（5分钟）代替'300s'（300秒），或使用'1d'（1天）代替'86400'（86400秒）。

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

last_foreach(/*/key?[group="主机组"])

exists_foreach函数不支持使用时间周期。

附加参数

bucket_rate_foreach

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

bucket_rate_foreach(监控项 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(监控项 filter,time period,<operator>,<pattern>)

其中：

• 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。

根据可用性的行为表现

下表说明了每个函数在主机/监控项和历史数据可用性受限时的行为。

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