Язык запросов в Monitoring
В этом разделе описан язык запросов Yandex Monitoring. Он используется для преобразования метрик при настройке дашбордов и алертов, а также в API-методе MetricsData.read.
Загрузка метрик
Выбирайте множество метрик с помощью имени метрик и набора селекторов, фильтрующих значения меток (подробнее в разделе Метки). Получившиеся наборы метрик можно использовать в алертах или передавать в функцию в качестве аргумента.
Укажите имя метрики, а также обязательные метки
folderId
иservice
. Тогда запросcpu_usage{folderId="zoeu2rgjpqak********", service="compute"}
вернет метрики с именемcpu_usage
для всех виртуальных машин сервиса Yandex Compute Cloud в каталоге с идентификаторомzoeu2rgjpqak********
.
Важно
Учитывайте особенности метки folderId
:
-
Значение метки должно совпадать с выбранным каталогом, запрашивать данные из других каталогов нельзя. Это справедливо для всех вариантов применения языка запросов: при построении графиков в Обзоре метрик или на дашбордах, при создании алертов или при вызове API-методов.
-
При вызове API-методов значение метки не добавляется в тело запроса (в поле
query
).folderId
следует передавать в HTTP-запросе как query-параметр.
Селектор состоит из имени метки, оператора и выражения, описывающего множество значений меток.
В языке запросов 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 — набор временных рядов (метрик);
- number — вещественное число;
- string — строка в одинарных или двойных кавычках;
- duration — временной промежуток в формате
15s, 10m, 3h, 7d, 2w.
(записывается без кавычек); - bool – логический тип, может принимать одно из двух значений:
true
илиfalse
. - scalar – вещественное число с плавающей точкой двойной точности по стандарту IEEE 754
, включая специальное значениеNaN
.
Примечание
При записи вещественных чисел поддерживается запись с мантиссой, а также следующие суффиксы:
k
— 103;M
— 106;G
— 109;T
— 1012;P
— 1015;E
– 1018.
Функции
Агрегация
Функции агрегации агрегируют значения временного ряда в текущем временном диапазоне.
Важно
Агрегационные функции принимают в качестве входного аргумента вектор метрик timeseries_vector. Он должен содержать только один временной ряд, в противном случае функция вернет ошибку выполнения.
При использовании агрегационных функций убедитесь, что селектор возвращает один временной ряд. При необходимости воспользуйтесь функциями комбинирования.
avg
Возвращает среднее значение (для временных рядов — взвешенное среднее) набора элементов или NaN
для пустого временного ряда.
Функция avg имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- avg(arg0: scalar[]): scalar
- avg(arg0: timeseries_vector): scalar
count
Возвращает количество точек для метрики или количество вектора чисел.
Функция count имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- count(arg0: scalar[]): scalar
- count(arg0: timeseries_vector): scalar
integrate
Возвращает интегрированную сумму значений или 0 для пустого временного ряда.
Функция integrate имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- integrate(arg0: scalar[]): scalar
- integrate(arg0: timeseries_vector): scalar
iqr
Возвращает межквартильный интервал
Функция iqr имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- iqr(arg0: scalar[]): scalar
- iqr(arg0: timeseries_vector): scalar
last
Возвращает последнее значение, отличное от NaN
или NaN
, для пустого временного ряда.
Функция last имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- last(arg0: scalar[]): scalar
- last(arg0: timeseries_vector): scalar
max
Возвращает максимальное значение или NaN
для пустого временного ряда.
Функция max имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- max(arg0: scalar[]): scalar
- max(arg0: timeseries_vector): scalar
median
Возвращает медиану значений или NaN
для пустого временного ряда.
Функция median имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- median(arg0: scalar[]): scalar
- median(arg0: timeseries_vector): scalar
min
Возвращает минимальное значение или NaN
для пустого временного ряда.
Функция min имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- min(arg0: scalar[]): scalar
- min(arg0: timeseries_vector): scalar
percentile
Возвращает значение процентиля для набора значений. Уровень процентиля задается в обязательном параметре level в виде числа от 0 до 100.
Функция percentile имеет следующие варианты перегрузки функции в зависимости от типа входного параметра values (массив чисел, метрика или вектор метрик):
- percentile(level: scalar, values: scalar[]): scalar
- percentile(level: scalar, values: timeseries_vector): scalar
random
Возвращает случайный элемент из набора значений.
Функция random имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- random(arg0: scalar[]): scalar
- random(arg0: timeseries_vector): scalar
std
Возвращает несмещенную оценку стандартного отклонения для набора значений (или NaN
для пустого временного ряда), вычисленную по следующей формуле:
где:
- — значение из вектора значений (или точек временного ряда);
- — среднее значение;
- – количество значений.
Функция std имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- std(arg0: scalar[]): scalar
- std(arg0: timeseries_vector): scalar
sum
Возвращает сумму всех значений из набора или 0 для пустого временного ряда.
Функция sum имеет следующие варианты перегрузки функции в зависимости от типа входного параметра arg0 (массив чисел, метрика или вектор метрик):
- sum(arg0: scalar[]): scalar
- sum(arg0: timeseries_vector): scalar
Комбинирование
Функции комбинирования агрегируют вектор метрик в одну метрику или вектор метрик.
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(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с минимальным средним значением.
bottom_count
bottom_count(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с минимальным количеством значений.
bottom_last
bottom_last(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с минимальным последним значением.
bottom_max
bottom_max(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с минимальным значением максимума.
bottom_min
bottom_min(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с минимальным значением минимума.
bottom_sum
bottom_sum(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с минимальным значением суммы.
top_avg
top_avg(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с максимальным средним значением.
top_count
top_count(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с максимальным количеством значений.
top_last
top_last(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с максимальным последним значением.
top_max
top_max(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с максимальным значением максимума.
top_min
top_min(limit: number, source: timeseries_vector): timeseries_vector
Возвращает limit метрик с максимальным значением минимума.
top_sum
top_sum(limit: number, source: timeseries_vector): 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_below(source: timeseries_vector, threshold: number): timeseries_vector
Отбрасывает точки со значением ниже порога threshold (значение не включается). В отброшенных точках значение метрики будет равно NaN
.
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
Вычисляет функцию Хевисайда
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 час.
moving_sum
moving_sum(source: timeseries_vector, window: duration): timeseries_vector
Вычисляет скользящую сумму с шириной окна window.
Например, запрос moving_sum({...}, 1d)
вернет скользящую сумму с окном в 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}}
, чтобы подставить в новое имя метрики значение метки.
constant_line
Возвращает постоянную линию, состоящую из двух точек в начале и конце интервала со значением value.
constant_line(value: scalar): timeseries_vector
При указании опционального параметра grid функция заполняет текущий временной интервал точками со значением value и шагом grid между точками.
constant_line(value: scalar, grid: duration): timeseries_vector
Важно
Функцию constant_line следует использовать только для отображений линий на графике. Использование функции в вычислениях приведет к некорректному результату, так как функция возвращает временной ряд только из двух точек в начале и конце интервала определения.
drop_empty_series
drop_empty_series(source: timeseries_vector): timeseries_vector
Отбрасывает временные ряды, в которых в заданном временном диапазоне либо нет точек, либо все точки со значением NaN
.