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

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

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

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

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

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

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

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

  Селектор host="*" вернет все метрики, у которых есть метка host.

• label="<glob-выражение>" — возвращает все метрики, у которых есть метки, значения которых удовлетворяют glob-выражению.

  • * — любое количество символов (в том числе отсутствие).

    name="folder*" вернет все метрики, у которых значение метки name начинается с префикса folder.

  • ? — один произвольный символ.

    name="metric?" вернет все метрики, у которых в значении метки name есть один символ после metric.

  • | — все указанные варианты.

    name="metric1|metric2" вернет две метрики со значениями метки name=metric1 и name=metric2.

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

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

Например:

A: "temperature"{folderId="my_folder_id", service="custom", room="bedroom", building="home", sensor="sensor1" }

B: "temperature"{folderId="my_folder_id", service="custom", room="bedroom", building="home", sensor="sensor2" }

C: (A + B) / 2

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

Типы данныхТипы данных

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

• timeseries_vector — набор временных рядов (метрик).

  Пример объекта типа timeseries_vector. Следующее выражение вернет вектор метрик с различными значениями метки host:

  {service='compute', host='*', name='exceptionCount'}
  

• number — вещественное число.

• string — строка в одинарных или двойных кавычках.

• duration — временной промежуток в формате 15s, 10m, 3h, 7d, 2w (записывается без кавычек).

• bool – логический тип, может принимать одно из двух значений: true или false.

• scalar – вещественное число с плавающей точкой двойной точности по стандарту IEEE 754, включая специальное значение NaN. Примеры объектов типов scalar: 101, 75.3, 20G, 1E-3.

ФункцииФункции

• Агрегация
  • avg
  • count
  • integrate
  • iqr
  • last
  • max
  • median
  • min
  • percentile
  • random
  • std
  • sum
• Комбинирование
  • histogram_avg
  • histogram_cdfp
  • histogram_count
  • histogram_percentile
  • histogram_sum
  • series_avg
  • series_max
  • series_min
  • series_percentile
  • series_sum
• Ранжирование
  • 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
  • moving_sum
  • non_negative_derivative
  • pow
  • ramp
  • replace_nan
  • round
  • shift
  • sign
  • sqrt
  • trunc
• Другое
  • alias
  • constant_line
  • drop_empty_series

АгрегацияАгрегация

Функции агрегации агрегируют значения временного ряда в текущем временном диапазоне.

avgavg

Возвращает среднее значение (для временных рядов — взвешенное среднее) набора элементов или NaN для пустого временного ряда.

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

• avg(arg0: scalar[]): scalar
• avg(arg0: timeseries_vector): scalar

countcount

Возвращает количество точек для метрики или количество вектора чисел.

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

• count(arg0: scalar[]): scalar
• count(arg0: timeseries_vector): scalar

integrateintegrate

Возвращает интегрированную сумму значений или 0 для пустого временного ряда.

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

• integrate(arg0: scalar[]): scalar
• integrate(arg0: timeseries_vector): scalar

iqriqr

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

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

• iqr(arg0: scalar[]): scalar
• iqr(arg0: timeseries_vector): scalar

lastlast

Возвращает последнее значение, отличное от NaN или NaN, для пустого временного ряда.

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

• last(arg0: scalar[]): scalar
• last(arg0: timeseries_vector): scalar

maxmax

Возвращает максимальное значение или NaN для пустого временного ряда.

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

• max(arg0: scalar[]): scalar
• max(arg0: timeseries_vector): scalar

medianmedian

Возвращает медиану значений или NaN для пустого временного ряда.

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

• median(arg0: scalar[]): scalar
• median(arg0: timeseries_vector): scalar

minmin

Возвращает минимальное значение или NaN для пустого временного ряда.

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

• min(arg0: scalar[]): scalar
• min(arg0: timeseries_vector): scalar

percentilepercentile

Возвращает значение процентиля для набора значений. Уровень процентиля задается в обязательном параметре level в виде числа от 0 до 100.

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

• percentile(level: scalar, values: scalar[]): scalar
• percentile(level: scalar, values: timeseries_vector): scalar

randomrandom

Возвращает случайный элемент из набора значений.

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

• random(arg0: scalar[]): scalar
• random(arg0: timeseries_vector): scalar

stdstd

Возвращает несмещенную оценку стандартного отклонения для набора значений (или NaN для пустого временного ряда), вычисленную по следующей формуле:

$$\begin{array}{c} s=\sqrt{\frac{1}{n-1}\sum_{i=1}^n\left(x_i-\bar{x}\right)^2} \end{array}{} ,$$

где:

• $x_i$ — значение из вектора значений (или точек временного ряда);
• $\bar{x}$ — среднее значение;
• $n$ – количество значений.

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

• std(arg0: scalar[]): scalar
• std(arg0: timeseries_vector): scalar

sumsum

Возвращает сумму всех значений из набора или 0 для пустого временного ряда.

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

• sum(arg0: scalar[]): scalar
• sum(arg0: timeseries_vector): scalar

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

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

histogram_avghistogram_avg

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

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

histogram_cdfphistogram_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_counthistogram_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_percentilehistogram_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_sumhistogram_sum

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

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

series_avgseries_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_maxseries_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_minseries_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_percentileseries_percentile

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

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

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

series_sumseries_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_avgbottom_avg

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

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

bottom_countbottom_count

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

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

bottom_lastbottom_last

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

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

bottom_maxbottom_max

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

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

bottom_minbottom_min

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

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

bottom_sumbottom_sum

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

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

top_avgtop_avg

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

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

top_counttop_count

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

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

top_lasttop_last

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

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

top_maxtop_max

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

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

top_mintop_min

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

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

top_sumtop_sum

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

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

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

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

absabs

abs(source: timeseries_vector): timeseries_vector

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

asapasap

asap(source: timeseries_vector): timeseries_vector

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

ceilceil

ceil(source: timeseries_vector): timeseries_vector

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

derivativederivative

derivative(source: timeseries_vector): timeseries_vector

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

diffdiff

diff(source: timeseries_vector): timeseries_vector

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

drop_abovedrop_above

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

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

drop_belowdrop_below

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

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

drop_nandrop_nan

drop_nan(source: timeseries_vector): timeseries_vector

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

expexp

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

floorfloor

floor(source: timeseries_vector): timeseries_vector

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

fractfract

fract(source: timeseries_vector): timeseries_vector

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

heavisideheaviside

heaviside(source: timeseries_vector): timeseries_vector

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

integralintegral

integral(source: timeseries_vector): timeseries_vector

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

loglog

log(source: timeseries_vector): timeseries_vector

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

moving_avgmoving_avg

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

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

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

moving_percentilemoving_percentile

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

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

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

moving_summoving_sum

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

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

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

non_negative_derivativenon_negative_derivative

non_negative_derivative(source: timeseries_vector): timeseries_vector

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

powpow

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

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

rampramp

ramp(source: timeseries_vector): timeseries_vector

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

replace_nanreplace_nan

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

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

roundround

round(source: timeseries_vector): timeseries_vector

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

shiftshift

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

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

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

signsign

sign(source: timeseries_vector): timeseries_vector

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

sqrtsqrt

sqrt(source: timeseries_vector): timeseries_vector

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

trunctrunc

trunc(source: timeseries_vector): timeseries_vector

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

ДругоеДругое

aliasalias

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

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

constant_lineconstant_line

Возвращает постоянную линию, состоящую из двух точек в начале и конце интервала со значением value.

constant_line(value: scalar): timeseries_vector

При указании опционального параметра grid функция заполняет текущий временной интервал точками со значением value и шагом grid между точками.

constant_line(value: scalar, grid: duration): timeseries_vector

drop_empty_seriesdrop_empty_series

drop_empty_series(source: timeseries_vector): timeseries_vector

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