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, и может быть опущен:

last_foreach(/*/ключ?[group="группа узлов сети"])

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

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

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

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

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

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

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

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

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

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