Documentation
Table of Contents
1 Функції Foreach
Огляд
Функції foreach використовуються в сукупних обчисленнях, щоб повернути одне сукупне значення для кожного елемента, вибраного використаним item filter.
Наприклад, функція avg_foreach поверне середнє значення з історії кожного вибраного елемента протягом указаного інтервалу часу.
Фільтр елементів є частиною синтаксису, який використовується функціями foreach. У фільтрі елементів підтримується використання символів підстановки, тому потрібні елементи можна вибирати досить гнучко.
Supported functions
| Function | Description |
|---|---|
| avg_foreach | Returns the average value for each item. |
| bucket_rate_foreach | Returns pairs (bucket upper bound, rate value) suitable for use in the histogram_quantile() function, where "bucket upper bound" is the value of item key parameter defined by the <parameter number> parameter. |
| count_foreach | Returns the number of values for each item.. |
| exists_foreach | Returns the number of currently enabled items. |
| last_foreach | Returns the last value for each item. |
| max_foreach | Returns the maximum value for each item. |
| min_foreach | Returns the minimum value for each item. |
| sum_foreach | Returns the sum of values for each item. |
Синтаксис функції
Функції foreach підтримують два загальні параметри: item filter (деталі див. нижче) і time period:
Наприклад:
avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)
поверне п’ятихвилинне середнє значення кожного елемента «mysql.qps» у групі сервера MySQL.
Зауважте, що деякі функції підтримують додаткові параметри.
Item filter
The first parameter allows to filter the items we are interested in. A complex filter may be used, referencing the item key, host group and tags, as illustrated by the examples:
| Syntax example | Description |
|---|---|
| /host/key[abc,*] | Matches similar items on this host. |
| /*/key | Matches the same item of any host. |
| /*/key?[group="ABC" and tag="tagname:value"] | Matches the same item of any host from the ABC group having 'tagname:value' tags. |
| /*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] | Matches similar items of any host from the ABC or DEF group with the respective tags. |
All referenced items must exist and collect data. Only enabled items on enabled hosts are included in the calculations.
If the item key of a referenced item is changed, the filter must be updated manually.
Specifying a parent host group includes the parent group and all nested host groups with their items.
Період часу
Другий параметр дозволяє вказати період часу для агрегації. Період часу можна виразити лише як час, кількість значень (з префіксом #) не підтримується.
Підтримувані одиниці вимірювання можна використовувати в цьому параметрі для зручності, наприклад, «5m» (п’ять хвилин) замість «300s» (300 секунд) або «1d» (один день) замість «86400» (86400 секунд).
Період часу ігнорується сервером, якщо він передається за допомогою функції last_foreach, тому його можна пропустити:
Період часу не підтримується функцією exists_foreach.
Додаткові параметри
Третій додатковий параметр підтримується функцією bucket_rate_foreach:
де <номер параметра> — це позиція значення «відра» в ключі елемента. Наприклад, якщо значення «відра» в myItem[aaa,0.2] дорівнює «0.2», то його позиція дорівнює 2.
Значення за замовчуванням <номер параметра> — «1».
Перегляньте сукупні обчислення, щоб отримати додаткові відомості та приклади використання функцій foreach.
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.