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 函数支持两个常用参数 - 监控项过滤器 (详见下文) 和 时间段：

  1. foreach_function(item filter,time period)

例如：

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

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

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

监控项过滤器语法

监控项过滤器：

  1. /host/key[parameters]?[conditions]

由四部分组成，其中：

  • 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开始支持），可以省略：：

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

exists_foreach 函数不支持时间段。

附加参数

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

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

其中 <参数编号> 是“bucket”值在监控项键的位置。例如，如果myItem[aaa,0.2] 中的“bucket”值为 ‘0.2’，则其位置为 2。

<参数 编号> 的默认值为“1”。

count_foreach

count_foreach 函数支持第三和第四个可选参数：

  1. count_foreach(item filter,time period,<operator>,<pattern>)

其中：

  • 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忽略11忽略1n/a
last_foreach忽略返回最后的值忽略忽略忽略忽略
max_foreach忽略返回最大值忽略忽略忽略忽略
min_foreach忽略返回最小值忽略忽略忽略忽略
sum_foreach忽略饭回值的和忽略忽略忽略忽略

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