1 循环处理函数

概述

Foreach函数用于aggregate calculations中,为每个通过监控项过滤器选中的监控项返回一个聚合值。函数将返回值的array。

例如,avg_foreach函数将返回值的array,其中每个值代表选定监控项在指定时间区间内的历史数据平均值

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

支持的函数

函数 描述
avg_foreach 返回每个监控项的平均值。
bucket_rate_foreach 返回适用于1-聚合函数函数的(桶上限值,速率值)对,其中"桶上限值"是由<参数编号>参数定义的监控项键参数值。
count_foreach 返回每个监控项的数值数量。
exists_foreach 为每个启用的监控项返回'1'。
last_foreach 返回每个监控项的最后一个值。
max_foreach 返回每个监控项的最大值。
min_foreach 返回每个监控项的最小值。
sum_foreach 返回每个监控项的数值总和。

函数语法

Foreach函数支持两个通用参数:item filter(详见下文)和time period

foreach_function(监控项 过滤器,时间范围)

例如:

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

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

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

监控项 过滤器语法

监控项过滤器:

/主机/键名[参数]?[条件表达式]

由四部分组成,其中:

  • 主机 - 主机名称
  • key - 监控项键值(不含参数)
  • parameters - 监控项键值参数
  • conditions - 基于主机组和/或监控项标签的条件表达式

空格仅允许出现在条件表达式内部。

通配符使用规则

  • 通配符可用于替代主机名称、监控项键值或单个监控项键值参数
  • 主机名称或监控项键值必须至少有一项不使用通配符。因此/host/*/*/key是有效过滤器,但/*/*无效
  • 通配符不能用于主机名称、监控项键值或键值参数的部分内容
  • 单个通配符不能匹配多个监控项键值参数。每个参数必须单独指定通配符(例如key[abc,*,*]

条件表达式语法

条件表达式支持:

  • 操作数:
    • group - 主机组
    • tag - 监控项标签
    • "<text>" - string常量,使用\转义符来转义"\
  • 区分大小写的string比较运算符:=<>
  • 逻辑运算符:andornot
  • 括号分组:( )

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

在过滤器中指定标签时(如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组中具有相应标签的任意主机上的相似监控项

所有被引用的监控项必须存在且正在采集数据。计算时仅包含已启用的主机上的启用项。

如果被引用监控项的键值发生变更,必须手动更新过滤器。

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

时间段

第二个参数用于指定聚合的时间周期。该时间周期仅能以时间单位表示,不支持以数值量(前缀为#)的形式指定。

为方便起见,该参数可使用Supported unit symbols,例如用"5m"(五分钟)替代"300s"(300秒),或用"1d"(一天)替代"86400"(86400秒)。

若与last_foreach函数同时使用,服务端将忽略时间周期参数,因此可省略:

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

exists_foreach函数不支持时间周期参数。

附加参数

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

bucket_rate_foreach(监控项 过滤器,时间周期,<参数序号>)

其中<参数序号>表示"bucket"值在监控项键中的位置。例如,若myItem[aaa,0.2]中的"bucket"值为'0.2',则其位置为2。

<参数序号>的默认值为'1'。

关于foreach函数的使用详情及示例,请参阅aggregate calculations

根据可用性的行为表现

下表展示了各函数在主机/监控项和历史数据可用性受限时的行为表现。

函数 禁用主机 有数据的不可用主机 无数据的不可用主机 禁用监控项 不支持的监控项 数据检索错误(SQL)
avg_foreach 忽略 返回平均值 忽略 忽略 忽略 忽略
bucket_rate_foreach 忽略 返回分桶率 忽略 忽略 忽略 忽略
count_foreach 忽略 返回计数 0 忽略 忽略 忽略
exists_foreach 忽略 1 1 忽略 1 不适用
last_foreach 忽略 返回最后值 忽略 忽略 忽略 忽略
max_foreach 忽略 返回最大值 忽略 忽略 忽略 忽略
min_foreach 忽略 返回最小值 忽略 忽略 忽略 忽略
sum_foreach 忽略 返回总和 忽略 忽略 忽略 忽略

当监控项被忽略时,不会向聚合结果添加任何内容。