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：
例如：
avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)
将返回MySQL服务器组中每个'mysql.qps'监控项的5分钟平均值。
请注意，某些函数支持额外的参数。
监控项 过滤器语法
监控项过滤器：
由四部分组成，其中：
- 主机 - 主机名称
- key - 监控项键值（不含参数）
- parameters - 监控项键值参数
- conditions - 基于主机组和/或监控项标签的条件表达式
空格仅允许出现在条件表达式内部。
通配符使用规则
- 通配符可用于替代主机名称、监控项键值或单个监控项键值参数
- 主机名称或监控项键值必须至少有一项不使用通配符。因此
/host/*和/*/key是有效过滤器，但/*/*无效 - 通配符不能用于主机名称、监控项键值或键值参数的部分内容
- 单个通配符不能匹配多个监控项键值参数。每个参数必须单独指定通配符（例如
key[abc,*,*]）
条件表达式语法
条件表达式支持：
- 操作数：
- group - 主机组
- tag - 监控项标签
"<text>"- string常量，使用\转义符来转义"和\
- 区分大小写的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 函数支持第三个可选参数：
其中<参数序号>表示"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 | 忽略 | 返回总和 | 忽略 | 忽略 | 忽略 | 忽略 |
当监控项被忽略时，不会向聚合结果添加任何内容。