Язык запросов

Загрузка метрик
Типы данных
Функции

В этом разделе описан язык запросов Yandex Monitoring. Он используется для преобразования метрик при настройке дашбордов и алертов, а также в API-методе MetricsData.read.

Загрузка метрик

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

Укажите имя метрики, а также обязательные метки folderId и service. Тогда запрос cpu_usage{folderId="zoeu2rgjpqakq377q1h6", service="compute"} вернет метрики с именем cpu_usage для всех виртуальных машин сервиса Yandex Compute Cloud в каталоге с идентификатором zoeu2rgjpqakq377q1h6.

Селектор состоит из имени метки, оператора и выражения, описывающего множество значений меток.

В языке запросов Yandex Monitoring поддерживаются следующие выражения для фильтрации значений меток:

label="*" - возвращает все метрики, у которых присутствует указанная метка.

Cелектор host="*" вернет все метрики, у которых есть метка host.
label="<glob>" – возвращает все метрики, у которых есть метки, значения которых удовлетворяют glob-выражению.
- * — любое количество символов (в том числе отсутствие).
  
  name="folder*" вернет все метрики, у которых значение метки name начинается с префикса folder.
- ? — один произвольный символ.
  
  name="metric?" вернет все метки, у которых в значении метки name есть один символ после metric.
- | — все указанные варианты.
  
  name="metric1|metric2" вернет две метрики, со значениями метки name=metric1 и name=metric2.

Типы данных

В языке запросов Yandex Monitoring существуют следующие типы данных:

timeseries_vector – набор временных рядов (метрик).
number — вещественное число;
string – строка в одинарных или двойных кавычках;
duration – временной промежуток в формате 15s, 10m, 3h, 7d, 2w. (записывается без кавычек);

Функции

Комбинирование
Ранжирование
- bottom_avg
- bottom_count
- bottom_last
- bottom_max
- bottom_min
- bottom_sum
- top_avg
- top_count
- top_last
- top_max
- top_min
- top_sum
Преобразование
- abs
- asap
- ceil
- derivative
- diff
- drop_above
- drop_below
- drop_nan
- exp
- floor
- fract
- heaviside
- integral
- log
- moving_avg
- moving_percentile
- non_negative_derivative
- pow
- ramp
- replace_nan
- round
- shift
- sign
- sqrt
- trunc
Другое
- alias
- drop_empty_series

Комбинирование

Функции комбинирования агрегируют вектор метрик в одну метрику или вектор метрик.

histogram_avg

histogram_avg([bucketLabel: string], source: timeseries_vector): timeseries_vector

Вычисляет среднее значение распределения, заданного гистограммой. Опциональный параметр bucketLabel указывает, в какой метке содержатся значения интервалов гистограммы.

histogram_cdfp

Функция histogram_cdfp имеет следующие варианты использования (перегрузки функции) в зависимости от типа входных параметров from и to (число или массив чисел):

histogram_cdfp([from: number, to: number, bucketLabel: string], source: timeseries_vector): timeseries_vector
histogram_cdfp([from: number, to: number[], bucketLabel: string], source: timeseries_vector): timeseries_vector
histogram_cdfp([from: number[], to: number, bucketLabel: string], source: timeseries_vector): timeseries_vector
histogram_cdfp([from: number[], to: number[], bucketLabel: string], source: timeseries_vector): timeseries_vector

Вычисляет долю значений в гистограмме между интервалами, заданными в опциональных параметрах from и to. Если параметры не заданы, используются первый и последний интервал соответственно. Опциональный параметр bucketLabel указывает, в какой метке содержатся значения интервалов гистограммы.

histogram_count

Функция histogram_count имеет следующие варианты использования (перегрузки функции) в зависимости от типа входных параметров from и to (число или массив чисел):

histogram_count([from: number, to: number, bucketLabel: string], source: timeseries_vector): timeseries_vector
histogram_count([from: number, to: number[], bucketLabel: string], source: timeseries_vector): timeseries_vector
histogram_count([from: number[], to: number, bucketLabel: string], source: timeseries_vector): timeseries_vector
histogram_count([from: number[], to: number[], bucketLabel: string], source: timeseries_vector): timeseries_vector

Вычисляет количество значений в гистограмме между интервалами, заданными в опциональных параметрах from и to. Если параметры не заданы, будет использоваться первый и последний интервал соответственно. Опциональный параметр bucketLabel указывает, в какой метке содержатся значения интервалов гистограммы.

histogram_percentile

Функция histogram_percentile имеет следующие варианты использования (перегрузки функции) в зависимости от типа входных параметров from и to (число или массив чисел):

histogram_percentile(percentileLevel: number, [bucketLabel: string], source: timeseries_vector): timeseries_vector
histogram_percentile(percentileLevel: number[], [bucketLabel: string], source: timeseries_vector): timeseries_vector

Вычисляет значения процентиля распределения, заданного гистограммой. Уровень процентиля задается в обязательном параметре percentileLevel в виде одного числа или массива чисел от 0 до 100. Опциональный параметр bucketLabel указывает, в какой метке содержатся значения интервалов гистограммы.

histogram_sum

histogram_sum([bucketLabel: string], source: timeseries_vector): timeseries_vector

Вычисляет сумму значений гистограммы. Опциональный параметр bucketLabel указывает, в какой метке содержатся значения интервалов гистограммы.

series_avg

Функция series_avg имеет следующие варианты использования (перегрузки функции) в зависимости от типа входного параметра key (строка или массив строк):

series_avg([key: string], source: timeseries_vector): timeseries_vector
series_avg([key: string[]], source: timeseries_vector): timeseries_vector

Агрегирует временные ряды в один (или несколько), применяя агрегационную функцию avg (среднее) для каждого момента времени. Опциональный параметр key содержит строку или массив строк со списком меток, по которым выполняется группировка.

Например, запрос series_avg({...}) в каждой точке вычислит среднее значение среди всех загруженных метрик.

Запрос series_avg("host", {...}) для каждого значения метки host вычислит среднее значение среди всех загруженных метрик.

Запрос series_avg(["host", "disk"], {...}) для каждой комбинации значений меток host и disk вычислит среднее значение среди всех загруженных метрик.

series_max

Функция series_max имеет следующие варианты использования (перегрузки функции) в зависимости от типа входного параметра key (строка или массив строк):

series_max([key: string], source: timeseries_vector): timeseries_vector
series_max([key: string[]], source: timeseries_vector): timeseries_vector

Агрегирует временные ряды в один (или несколько), применяя агрегационную функцию max (максимум) для каждого момента времени. Опциональный параметр key содержит строку или массив строк со списком меток, по которым выполняется группировка. Примеры запросов с использованием параметра key смотрите в разделе series_avg.

series_min

Функция series_min имеет следующие варианты использования (перегрузки функции) в зависимости от типа входного параметра key (строка или массив строк):

series_min([key: string], source: timeseries_vector): timeseries_vector
series_min([key: string[]], source: timeseries_vector): timeseries_vector

Агрегирует временные ряды в один (или несколько), применяя агрегационную функцию min (минимум) для каждого момента времени. Опциональный параметр key содержит строку или массив строк со списком меток, по которым выполняется группировка. Примеры запросов с использованием параметра key смотрите в разделе series_avg.

series_percentile

Функция series_percentile имеет следующие варианты использования (перегрузки функции) в зависимости от типа входного параметра rank (число или массив чисел):

series_percentile(rank: number, source: timeseries_vector): timeseries_vector
series_percentile(rank: number[], source: timeseries_vector): timeseries_vector

Агрегирует временные ряды в один (или несколько), применяя агрегационную функцию percentile (процентиль) для каждого момента времени.

series_sum

Функция series_sum имеет следующие варианты использования (перегрузки функции) в зависимости от типа входного параметра key (строка или массив строк):

series_sum([key: string], source: timeseries_vector): timeseries_vector
series_sum([key: string[]], source: timeseries_vector): timeseries_vector

Агрегирует временные ряды в один (или несколько), применяя агрегационную функцию sum (сумма) для каждого момента времени. Опциональный параметр key содержит строку или массив строк со списком меток, по которым выполняется группировка. Примеры запросов с использованием параметра key смотрите в разделе series_avg.

Ранжирование

Функции ранжирования упорядочивают вектор метрик по значению агрегационной функции в текущем временном окне и возвращают из него несколько первых (верхних) или последних (нижних) временных рядов. Параметр limit указывает какое количество метрик вернет функция.

bottom_avg

bottom_avg(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с минимальным средним значением.

bottom_count

bottom_count(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с минимальным количеством значений.

bottom_last

bottom_last(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с минимальным последним значением.

bottom_max

bottom_max(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с минимальным значением максимума.

bottom_min

bottom_min(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с минимальным значением минимума.

bottom_sum

bottom_sum(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с минимальным значением суммы.

top_avg

top_avg(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с максимальным средним значением.

top_count

top_count(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с максимальным количеством значений.

top_last

top_last(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с максимальным последним значением.

top_max

top_max(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с максимальным значением максимума.

top_min

top_min(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с максимальным значением минимума.

top_sum

top_sum(source: timeseries_vector, limit: number): timeseries_vector

Возвращает limit метрик с максимальным значением суммы.

Преобразование

Функции преобразования метрик для каждого временного ряда из набора метрик вычисляют в каждой точке новое значение.

abs

abs(source: timeseries_vector): timeseries_vector

Вычисляет абсолютное значение.

asap

asap(source: timeseries_vector): timeseries_vector

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

ceil

ceil(source: timeseries_vector): timeseries_vector

Округляет значения точек вверх до ближайшего целого числа.

derivative

derivative(source: timeseries_vector): timeseries_vector

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

diff

diff(source: timeseries_vector): timeseries_vector

Вычисляет разность между значениями каждой пары соседних точек.

drop_above

drop_above(source: timeseries_vector, threshold: number): timeseries_vector

Отбрасывает точки со значением выше порога threshold (значение не включается). В отброшенных точках значение метрики будет равно NaN.

drop_below

drop_above(source: timeseries_vector, threshold: number): timeseries_vector

drop_nan

drop_nan(source: timeseries_vector): timeseries_vector

Отбрасывает точки со значением NaN.

exp

Вычисляет экспоненциальную функцию: возводит e в степень, равную значению точек, где e=2.718281... – основание натурального логарифма.

floor

floor(source: timeseries_vector): timeseries_vector

Округляет значения точек вниз до ближайшего целого числа.

fract

fract(source: timeseries_vector): timeseries_vector

Выделяет вещественную часть значений точек.

heaviside

heaviside(source: timeseries_vector): timeseries_vector

Вычисляет функцию Хевисайда. Функция равна 1, если значения точек положительные, и равна 0, если значения точек отрицательные.

integral

integral(source: timeseries_vector): timeseries_vector

Вычисляет неопределенный интеграл методом трапеций.

log

log(source: timeseries_vector): timeseries_vector

Вычисляет натуральный логарифм.

moving_avg

moving_avg(source: timeseries_vector, window: duration): timeseries_vector

Вычисляет скользящее среднее с шириной окна window.

Например, запрос moving_avg({...}, 1d) вернет скользящее среднее с окном в 1 день.

moving_percentile

moving_percentile(source: timeseries_vector, window: duration, rank: number): timeseries_vector

Вычисляет скользящий процентиль: процентиль уровня rank (от 0 до 100) среди точек, попавших в окно шириной window.

Например, запрос moving_percentile({...}, 1h, 99.9) вернет скользящий 99,9-й процентиль с окном в 1 час.

non_negative_derivative

non_negative_derivative(source: timeseries_vector): timeseries_vector

Вычисляет производную: разность между значениями соседних точек, поделенную на интервал между ними. Если значение производной принимает отрицательное значение, вместо него используется значение NaN.

pow

pow(source: timeseries_vector, power: number): timeseries_vector

Вычисляет степенную функцию: возводит значение точек в степень power.

ramp

ramp(source: timeseries_vector): timeseries_vector

Заменяет точки с отрицательным значением на 0.

replace_nan

replace_nan(source: timeseries_vector, replace: number): timeseries_vector

Заменяет точки со значением NaN на значение replace.

round

round(source: timeseries_vector): timeseries_vector

Округляет значения до ближайшего целого.

shift

shift(source: timeseries_vector, window: duration): timeseries_vector

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

Например, shift({...}, 1w) – вернет метрики со смещением на неделю вперед, то есть в выбранном временном окне будут значения недельной давности.

sign

sign(source: timeseries_vector): timeseries_vector

Вычисляет функцию sgn(x). Функция равна 1 для положительных значений точек, 0 — для нулевых значений и -1 — для отрицательных значений.

sqrt

sqrt(source: timeseries_vector): timeseries_vector

Вычисляет квадратный корень значения точек.

trunc

trunc(source: timeseries_vector): timeseries_vector

Отбрасывает вещественную часть значения точек.

Другое

alias

alias(source: timeseries_vector, arg1: string): timeseries_vector

Переименовывает метрики. В аргументе можно использовать mustache-шаблонизацию в формате {{label}}, чтобы подставить в новое имя метрики значение метки.

drop_empty_series

drop_empty_series(source: timeseries_vector): timeseries_vector

Отбрасывает временные ряды, в которых в заданном временном диапазоне либо нет точек, либо все точки со значением NaN.