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
:
例如:
avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)
将返回MySQL服务器组中每个'mysql.qps'监控项的5分钟平均值。
注意某些函数支持额外的参数。
监控项过滤器:
由以下四个部分组成:
条件表达式内部仅允许存在空格
通配符用法
/host/*
和/*/key
是有效过滤器,但/*/*
无效。key[abc,*,*]
)。条件表达式
条件表达式支持:
"<text>"
- string常量,使用\
转义字符来转义"
和\
=
, <>
and
, or
, not
(
)
引用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函数一起使用,服务器会忽略时间周期参数,因此可省略:
exists_foreach函数不支持时间周期参数。
bucket_rate_foreach 函数支持第三个可选参数:
其中<parameter number>表示"bucket"值在监控项键中的位置。例如,如果myItem[aaa,0.2]中的"bucket"值是'0.2',那么它的位置就是2。
<parameter number>的默认值为'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 | 忽略 | 返回总和 | 忽略 | 忽略 | 忽略 | 忽略 |
若监控项被忽略,则不会向聚合结果添加任何内容。