Функции foreach

Обзор

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

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

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

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

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

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

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 - условия на основе группы узлов сети и/или тега элемента данных (в виде выражения)

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

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

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

Выражение conditions

Выражение conditions поддерживает:

• операнды:
  • group - группа узлов сети
  • tag - тег элемента данных
  • "<text>" - строковая константа с символом экранирования \ для экранирования " и \
• операторы сравнения строк с учётом регистра: =, <>
• логические операторы: 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,<номер параметра>)

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

Значение по умолчанию для <номер параметра> — '1'.

count_foreach

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

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

Где:

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

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

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

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

Поведение в зависимости от доступности

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

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