Querying/Basics

Прометеус предоставляет язык запросов PromQL (Premetheus Query Language), который позволяет выбирать и аггрегировать timeseries данные в реальном времени
Резльтат запроса может быть отображен в виде графика или таблицы интерфейсе прометеуса или может быть "поглащен" внешней системой через HTTP API

Expression language data types

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

• Instant vector - a set of time series containing a single sample for each time series, all sharing the same timestamp
• Range vector - a set of time series containing a range of data points over time for each time series
• Scalar - a simple numeric floating point value
• String - a simple string value; currently unused

Разные типы подходят для разных кейсов
Например только instant vector может быть отображен на графике

Literals

Строки можно определять в одинарных, двойных кавычках или тиках
PromQL следует принципам из Go, поэтому в двойных или одинарных кавычках \ начинает escape-sequence, за \ может следовать a, b, f, n, r, t, v или \
Конкретный символ может быть задан в octal формате \nnn или hexadecimal \xnn, \unnnn, \Unnnnnnnn
В тиках escape последовательности не обрабатываются. В отличие от Go, Prometheus не отменяет новую строку внутри тиков

"this is a string"
'these are unescaped: \n \\ \t'
`these are not unescaped: \n ' " \t`

Time series Selectors

Instant vector selectors

Instant vector selectors позволяют выбирать нобор timeseries и одно значение из каждого на какой-то конкретный timestamp

Пример ниже выберет все time series которые имеют http_requests_total в metric name:

http_requests_total

Можно сделать более тонкую фильтрацию добавив лейблы в фигрных скобках http_requests_total{label1="label1", label2="label2"}

Кроме знака равенства лейблы можно матчить следующими операторами:

• = - Select labels that are exactly equal to the provided string
• != - Select labels that are not equal to the provided string
• =~ - Select labels that regex-match the provided string
• !~ - Select labels that do not regex-match the provided string

Пример:

http_requests_total{environment=~"staging|testing|development",method!="GET"}

Vector selector должен иметь имя или не менее одного лейбла который матчится с непустой строкой

{job=~".*"}              # Bad! Потому что ".*" матчится с пустой строкой

{job=~".+"}              # Good!
{job=~".*",method="get"} # Good!

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

Каждая таймсерия идентифицируется именем и набором лейблов. Поэтому если собирать данные по какому-то имени и лейблам, а потом собирать по ним же другие данные, то график просто продолжит строиться из новых данных

Имена метрик можно матчить через внутренний лейбл __name__ (как на скрине выше)
http_requests_total -> {__name__="http_requests_total"}

А на следующем скриншоте наоборот
После изменения лейбла появился новый график

Имя метрики не может одним из этих слов:

• bool
• on
• ignoring
• group_left
• group_right

on{} # Bad!

Обходной путь - использовать лейбл __name__ (если уж очень нужны метрики с такими именами)

Range Vector Selectors

Range Vector selection работает точно так же как и instant vector selection, только возвращается массив значений вместо одного значения

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

http_requests_total{job="prometheus"}[5m] # за последние 5 минут

Time Durations

Диапазон указывается числом с приставкой (unit):

• ms - milliseconds
• s - seconds
• m - minutes
• h - hours
• d - days - assuming a day has always 24h
• w - weeks - assuming a week has always 7d
• y - years - assuming a year has always 365d

Эти юниты (единицы измерения) можно комбинировать, конкатенируя их (1h20m30s), но юниты должны идти от большего к меньшему и могут встречаться лишь однажды (то есть нельзя 10h2h)

Offset modifier

offset позволяет сдвинуть таймсерию на указанное время назад и получить значение метрики из прошлого

http_requests_total offset 5m

Важно отметить что модификатор offset всегда должен идти после селектора
То есть это валидно:

sum(http_requests_total{method="GET"} offset 5m) // GOOD.

А это нет:

sum(http_requests_total{method="GET"}) offset 5m // INVALID.

Пример, питимунтный диапазон неделю назад:

rate(http_requests_total[5m] offset 1w)

Задавая отрицательный offset можно двигаться вперед во времени
Но для этого нужно включить этот функционал опцией --enable-feature=promql-negative-offset

@ modifier

Позволяет изменить evaluation time для конкретного instant или range vector в запросе
В векторе будут значения на момент времени указанный через @ в timestamp
Другими словами этот модификатор позволяет вернуть значение метирки на конкретный момент времени

Но его тоже нужно включать опцией --enable-feature=promql-at-modifier

И он так же должен следовать за селектором

sum(http_requests_total{method="GET"} @ 1609746000) // GOOD.
sum(http_requests_total{method="GET"}) @ 1609746000 // INVALID.

Работает и с range vectors
От указанного таймстемпа отступит указанное количество времени и покажет значения которые входят в диапазон между timestamp и timestamp-period

В следующих двух примерах это так же видно

At модификатор можно комбинировать с offset
Не важно в каком порядке
offset будет применяться относительно timestamp
Запросы ниже вернут одно и то же

# offset after @
http_requests_total @ 1609746000 offset 5m
# offset before @
http_requests_total offset 5m @ 1609746000

Так же можно использовать функции start() и end()

Subquery

Подзапрос позволяет запустить мгновенный (istant) запрос для заданного диапазона и разрешения (resolution)
Результат подзапроса это range vector

instant_query [<range>:<resolution>]

Пример

quantile_over_time(0.95, rate(node_network_receive_bytes_total[5m])[1h:1m])

Comments

Комменты начинаются с решетки, коммент - вся строка

# This is a comment

Gotchas

https://prometheus.io/docs/prometheus/latest/querying/basics/#gotchas