Documentation
Table of Contents
1 Foreach 函数
概述
Foreach 函数用于聚合计算，为使用的监控项过滤器选择的每个监控项返回一个聚合值。
例如，avg_foreach 函数将在指定的时间间隔内返回每个选定监控项历史记录的平均值 值。
item filter 是 foreach 函数使用的语法的一部分。 监控项过滤器支持通配符的使用，可以非常灵活的选择需要的监控项。
支持的函数
| 功能 | 说明 |
|---|---|
| avg_foreach | 返回每个项目的平均值。 |
| bucket_rate_foreach | 返回适用于 histogram_quantile() 函数的对（桶上限，速率值），其中“桶上限”是值由 <parameter number> parameter 定义的监控项关键参数。 |
| count_foreach | 返回每个监控项的值的数量。 |
| exists_foreach | 返回当前启用的监控项数。 |
| last_foreach | 返回每个监控项的最后一个值。 |
| max_foreach | 返回每个监控项的最大值。 |
| min_foreach | 返回每个监控项的最小值。 |
| sum_foreach | 返回每个监控项的值的总和。 |
参数
Foreach 函数支持两个常用参数 - 监控项过滤器和时间段：
例如：
一些函数支持附加参数。
监控项过滤器语法
监控项过滤器：
· /host/key[parameters]?[conditions]
由四部分组成，其中：
- · host - 主机名
- · key - 监控项键（不带参数） *·parameters - 监控项键关键参数
- · conditions - 基于主机组和/或监控项标签的条件（作为表达式）
仅在条件表达式内允许使用空格。
通配符的使用
- · 通配符可用于替换主机名、监控项键或单个监控项键参数。
- · 主机或监控项键必须在没有通配符的情况下指定。 所以
/host/*和/*/key是有效的过滤器，但是/*/*是无效的。 - · 主机名、监控项键、监控项键参数的部分不能使用通配符。
- · 通配符不匹配多个监控项键参数。 因此，必须为分隔中的每个参数指定一个通配符（即
key[abc,*,*]）。
条件表达式
条件表达式支持：
- · 操作数： · * · group - 主机组 · * · tag - 标签 · * ·
"<text>"- 字符串常量，用\转义字符转义"和\ - · 区分大小写的字符串比较运算符：
=、<> - · 逻辑运算符：
and、or、not - · 用括号分组：
()
字符串常量的引号是强制性的。 仅支持区分大小写的完整字符串比较。
例子
可以使用复杂的过滤器，引用监控项键、主机组和标签，如示例所示：
| 语法示例 | 说明 |
|---|---|
/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 组的任何主机的类似监控项与各自的标签匹配。 |
所有引用的监控项都必须存在并收集数据。 计算中仅包含已启用主机上的已启用监控项。
如果引用的监控项键发生更改，则必须手动更新过滤器。
指定父主机组包括父组和所有嵌套的主机组及其监控项。
时间段
second 参数允许指定时间段 聚合。时间段只能表示为时间，数量 不支持值（以 # 为前缀）。
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”。
Behavior depending on availability
The following table illustrates how each function behaves in cases of limited availability of host/item and history data.
| Function | Disabled host | Unavailable host with data | Unavailable host without data | Disabled item | Unsupported item | Data retrieval error (SQL) |
|---|---|---|---|---|---|---|
| avg_foreach | ignore | return avg | ignore | ignore | ignore | ignore |
| bucket_rate_foreach | ignore | return bucket rate | ignore | ignore | ignore | ignore |
| count_foreach | ignore | return count | 0 | ignore | ignore | ignore |
| exists_foreach | ignore | 1 | 1 | ignore | 1 | n/a |
| last_foreach | ignore | return last | ignore | ignore | ignore | ignore |
| max_foreach | ignore | return max | ignore | ignore | ignore | ignore |
| min_foreach | ignore | return min | ignore | ignore | ignore | ignore |
| sum_foreach | ignore | return sum | ignore | ignore | ignore | ignore |
If the item is ignored, nothing is added to the aggregation.