Функции foreach

Обзор

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

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

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

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

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

Функции foreach поддерживают два общих параметра: фильтр_элементов_данных (подробнее смотрите ниже) и период_времени:

функция_foreach(фильтр_элементов_данных,период_времени)

Например:

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

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

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

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

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

/узел_сети/ключ[параметры]?[условия]

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

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

Использование подстановочных символов

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

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

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

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

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

Примеры

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

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

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

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

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

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

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

last_foreach(/*/ключ?[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.

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

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

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