Как работать с PromQL

В этом разделе можно узнать об особенностях поддержки PromQL в StatsHouse:

• Что такое PromQL?
• Редактор PromQL-запросов
• Особенности поддержки PromQL в StatsHouse
  • Результат выполнения запроса — это агрегат
  • Выбор компонентов агрегата с помощью селектора what
  • Гистограммы в StatsHouse — это структуры t-digest
  • По умолчанию группировка не выполняется
• Расширения PromQL в StatsHouse
  • what и by
  • Привязывание переменных на дашборде
  • Range vector и instant vector
  • Prefix sum
  • default

Что такое PromQL?

PromQL (Prometheus Query Language) — это язык запросов для работы с временными рядами в системе Prometheus.

Мы решили поддержать PromQL, чтобы расширить возможности работы с данными в StatsHouse. PromQL предоставляет нужную функциональность, широко используется и хорошо документирован.

Познакомьтесь с оригинальной документацией PromQL.

Редактор PromQL-запросов

Чтобы открыть редактор PromQL-запросов, нажмите кнопку < > рядом с полем выбора метрики. Узнайте больше о редакторе PromQL-запросов.

Особенности поддержки PromQL в StatsHouse

Если у вас уже есть опыт работы с PromQL, вам важно знать, чем отличается поддержка PromQL в StatsHouse от привычного вам PromQL в системе Prometheus:

• Результат выполнения запроса — это агрегат, а не точное значение метрики в каждый момент времени.
• Выбрать компоненты агрегата можно с помощью селектора __what__.
• Гистограммы в StatsHouse представляют собой структуры t-digest.
• В StatsHouse не выполняется группировка по умолчанию.

Результат выполнения запроса — это агрегат

Система Prometheus хранит пары временная метка-значение. В отличие от Prometheus, StatsHouse хранит агрегированные данные, относящие ко временным интервалам (агрегаты).

Результат выполнения PromQL-запроса в StatsHouse зависит от

• минимального доступного интервала агрегации (т.е. от «возраста» данных),
• запрашиваемого интервала агрегации,
• разрешения метрики.

Агрегат содержит статистики count, sum, min, max, а также иногда тег String top (tag_s) и перцентили (при условии, что их запись включена). Они являются компонентами агрегата:

timestamp	metric	tag_1	tag_2	tag_s	count	sum	min	max	percentiles
13:45:05	toy_metric	...	...	...	...	...	...	...	...

Узнайте больше об агрегации в StatsHouse.

Выбор компонентов агрегата с помощью селектора what

• В системе Prometheus можно запрашивать точные значения. Prometheus хранит пары временная метка-значение, где значение — число с плавающей точкой, привязанное к конкретному моменту времени.
• В StatsHouse можно запрашивать только агрегаты, относящиеся к временному интервалу.

Чтобы получить компонент агрегата в StatsHouse, используйте селектор __what__. Вот список возможных значений:

"avg"
"count"
"countsec"
"max"
"min"
"sum"
"sumsec"
"stddev"
"stdvar"
"p25"
"p50"
"p75"
"p90"
"p95"
"p99"
"p999"
"cardinality"
"cardinalitysec"
"unique"
"uniquesec"

Это те же самые описательные статистики, которые можно выбирать в "кнопочном" интерфейсе StatsHouse. Постфикс "sec" означает, что значение нормализовано (поделено на интервал агрегации в секундах).

Например, этот селектор возвращает счётчик для метрики api_methods, привязанный к интервалу агрегации:

api_methods{__what__="count"}

Если в селекторе __what__ не указано значение, StatsHouse попытается "угадать" нужную вам статистику, основываясь на функциях PromQL, которые вы используете в своем запросе:

PromQL functions	StatsHouse interpretation
"increase" "irate" "rate" "resets"	__what__="count"
"delta" "deriv" "holt_winters" "idelta" "predict_linear"	__what__="avg"

Например, этот запрос возвращает rate счётчика метрики api_methods за пять минут:

rate(api_methods[5m])

Если "угадать" статистику не удаётся, StatsHouse возвращает счётчик для counter-метрик и среднее значение (сумму, делённую на счётчик) для value-метрик.

Гистограммы в StatsHouse — это структуры t-digest

В Prometheus есть «обычные» и «нативные» гистограммы. Скоро StatsHouse сможет поддержать «обычные». Больше информации о поддержке гистограмм появится, когда будет полностью реализована функциональность скрейпинга. Сейчас рекомендуется использовать гистограммы StatsHouse.

StatsHouse хранит гистограммы как t-digest. По умолчанию гистограммы для метрики не строятся — нужно включить запись перцентилей вручную.

Указать необходимый перцентиль нужно в селекторе __what__:

"p25"
"p50"
"p75"
"p90"
"p95"
"p99"
"p999"

Например, следующее выражение вернёт 99-й перцентиль:

api_methods{__what__="p99"}

По умолчанию группировка не выполняется

Если запросить данные в Prometheus по имени метрики, система вернёт все ряды данных для этой метрики —— все комбинации тегов.

В отличие от Prometheus, StatsHouse вернёт результат агрегирования. Например, запрос метрики "api_methods" в StatsHouse возвращает одну строку. Чтобы сгруппировать данные по тегам, укажите нужные теги, используя оператор __by__.

Расширения PromQL в StatsHouse

Поддержка PromQL в StatsHouse включает в себя ряд расширений.

what и by

Селекторы __what__ и __by__ помогают выразить стандартные запросы.

Привязывание переменных на дашборде

Чтобы привязать тег к созданной ранее переменной, используйте следующий синтаксис в PromQL-запросе:

tag_name:$variable_name

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

topk(5,api_methods{@what="countsec",0:$env})

Узнайте больше о настройке переменных на дашборде с использованием PromQL-графиков.

Range vector и instant vector

Функции над range vector также принимают instant vector, но не наоборот.

Prefix sum

Функция prefix_sum вычисляет префиксную сумму. Например, для последовательности 1, 2, 3, 4, 5, 6 она вернёт 1, 3, 6, 10, 15, 21.

default

Это бинарный оператор. Слева он принимает ряд, а справа — ряд или литерал.

• Если справа находится литерал, то значения NaN слева будут заменены на значение литерала справа.
• Если справа находится ряд, то логика сопоставления рядов такая же, как и для оператора or. Значения NaN слева заменяются соответствующими значениями справа.