1. Функции 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(фильтр_элементов_данных,период_времени,<номер_параметра>)

где <номер_параметра> — это положение значения «разряд» в ключе элемента данных. Например, если в myItem[aaa,0.2] значением «разряд» является «0.2», то его положение — это 2.

Значением по умолчанию для <номера параметра> является «1».

count_foreach

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

count_foreach(фильтр_элементов_данных,период_времени,<оператор>,<шаблон>)

Где:

• оператор is the conditional operator for item values (must be double-quoted). Supported operators:
  eq — равно
  ne — не равно
  gt — больше
  ge — больше или равно
  lt — меньше
  le — меньше или равно
  like — содержит подстроку шаблона (чувствительно к регистру)
  bitand — побитовое И
  regexp — чувствительное к регистру соответствие регулярному выражению, данному в шаблоне
  iregexp — нечувствительное к регистру соответствие регулярному выражению, данному в шаблоне
  
• шаблон — искомый шаблон (строковые аргументы должны быть в двойных кавычках); поддерживается, если в третьем параметре указан оператор.

Комментарии:

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

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

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

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

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