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

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>" - 字符串常量,用\转义字符转义"\
  • 区分大小写的字符串比较运算符:=<>
  • 逻辑运算符:andornot
  • 用括号分组:( )

字符串常量的引号是强制性的。 仅支持区分大小写的完整字符串比较。

当在过滤器中指定标签时 (即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开始支持),可以省略::

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

exists_foreach 函数不支持时间段。

附加参数

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

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

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

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

count_foreach

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

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

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