1. Функции foreach

Обзор

Функции foreach используются в агрегатных вычислениях для возврата одного агрегированного значения для каждого элемента данных, который выбран с помощью используемого фильтра элементов данных. Возвращается массив значений.

Например, функция avg_foreach вернет массив значений, где каждое значение — это среднее значение истории выбранного элемента данных за указанный временной интервал.

Фильтр элементов данных является частью синтаксиса, используемого функциями foreach. В фильтре элементов данных поддерживается использование подстановочных знаков, поэтому необходимые элементы можно выбирать весьма гибко.

Поддерживаемые функции

Синтаксис функции

Функции foreach поддерживают два общих параметра: item filter (подробности см. ниже) и time period:

foreach_function(item filter,time period)

Например:

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

вернет среднее значение за пять минут для каждого элемента данных mysql.qps в группе узлов сети MySQL.

Обратите внимание, что некоторые функции поддерживают дополнительные параметры.

Синтаксис фильтра элементов данных

Фильтр элементов данных:

/host/key[parameters]?[conditions]

состоит из четырех частей, где:
host - имя узла сети;
key - ключ элемента данных (без параметров);
parameters - параметры ключа элемента данных;
conditions - условия на основе группы узлов сети и/или тега элемента данных (в виде выражения).

Пробелы допускаются только внутри выражения условий.

Использование подстановочного знака

• Подстановочный знак можно использовать для замены имени узла сети, ключа элемента данных или отдельного параметра ключа элемента данных.
• Либо узел сети, либо ключ элемента данных должны быть указаны без подстановочного знака. Поэтому /host/* и /*/key являются допустимыми фильтрами, а /*/* - недопустимым.
• Подстановочный знак нельзя использовать для части имени узла сети, ключа элемента данных, параметра ключа элемента данных.
• Подстановочный знак не сопоставляется более чем с одним параметром ключа элемента данных. Поэтому для каждого параметра подстановочный знак должен указываться отдельно (то есть key[abc,*,*]).

Выражение условий

Выражение условий поддерживает:

• Операнды:
  group - группа узлов сети;
  tag - тег элемента данных;
  "<text>" - строковая константа, с использованием escape-символа \ для экранирования " и \.
• Операторы сравнения строк с учетом регистра: =, <>
• Логические операторы: and, or, not
• Группировку с помощью круглых скобок: ( )

Кавычки для строковых констант обязательны. Поддерживается только полное строковое сравнение с учетом регистра.

Примеры

Сложный фильтр может использоваться для ссылки на ключ элемента данных, группу узлов сети и теги, как показано в примерах:

Все указанные элементы данных должны существовать и собирать данные. В вычисления включаются только включенные элементы данных на включенных узлах сети. Элементы данных в неподдерживаемом состоянии не включаются.

Указание родительской группы узлов сети включает родительскую группу и все вложенные группы узлов сети с их элементами данных.

Период времени

Второй параметр позволяет указать период времени для агрегации. Период времени может быть задан только как время; количество значений (с префиксом #) не поддерживается.

Для удобства в этом параметре можно использовать поддерживаемые символы единиц измерения, например, 5m (пять минут) вместо 300s (300 секунд) или 1d (один день) вместо 86400 (86400 секунд).

Для функции last_foreach период времени является необязательным параметром (поддерживается начиная с Zabbix 7.0) и может быть опущен:

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

Период времени не поддерживается функцией exists_foreach.

Дополнительные параметры

bucket_rate_foreach

Функция bucket_rate_foreach поддерживает третий необязательный параметр:

bucket_rate_foreach(item filter,time period,<parameter number>)

где <parameter number> — это позиция значения "bucket" в ключе элемента данных. Например, если значение "bucket" в myItem[aaa,0.2] равно 0.2, то его позиция — 2.

Значение по умолчанию для <parameter number> — 1.

count_foreach

Функция count_foreach поддерживает третий и четвертый необязательные параметры:

count_foreach(item filter,time period,<operator>,<pattern>)

Где:

• operator — условный оператор для значений элементов данных (должен быть в двойных кавычках). Поддерживаемые operators:
  eq - равно
  ne - не равно
  gt - больше
  ge - больше или равно
  lt - меньше
  le - меньше или равно
  like - совпадает, если содержит шаблон (с учетом регистра)
  bitand - побитовое И
  regexp - совпадение с регулярным выражением, заданным в pattern, с учетом регистра
  iregexp - совпадение с регулярным выражением, заданным в pattern, без учета регистра.
  
• pattern — требуемый шаблон (строковые аргументы должны быть в двойных кавычках); поддерживается, если в третьем параметре указан operator.

Примечания:

• Необязательные параметры operator или pattern нельзя оставлять пустыми после запятой, их можно только полностью опустить.
• При использовании bitand в качестве третьего параметра четвертый параметр pattern можно указать как два числа, разделенные '/': number_to_compare_with/mask. count_foreach() вычисляет "побитовое И" для значения и mask и сравнивает результат с number_to_compare_with. Если результат "побитового И" равен number_to_compare_with, значение учитывается.
  Если number_to_compare_with и mask равны, достаточно указать только mask (без '/').
• При использовании regexp или iregexp в качестве третьего параметра четвертый параметр pattern может быть обычным или глобальным регулярным выражением (начинающимся с '@'). В случае глобальных регулярных выражений чувствительность к регистру наследуется из настроек глобального регулярного выражения. Для сопоставления regexp значения с плавающей точкой всегда будут представлены с 4 знаками после '.'. Также обратите внимание, что для больших чисел разница в десятичном (хранимом в базе данных) и двоичном (используемом сервером Zabbix) представлении может повлиять на 4-й десятичный знак.

См. агрегатные вычисления для получения дополнительных сведений и примеров использования функций foreach.

Поведение, зависящее от доступности

Следующая таблица иллюстрирует, как каждая функция ведёт себя в случае ограниченной доступности узла сети / элемента данных и данных истории.

Если для элемента данных указано игнорировать, к агрегированию ничего не добавляется.