Основы PromQL: синтаксис, операторы и базовые функции

PromQL - это язык запросов, встроенный в систему мониторинга Prometheus, предназначенный для извлечения, агрегации и анализа временных рядов. Он позволяет сформулировать точные запросы к данным, получаемым путем срыва со стороны целевых метрик и экспортёров. В основе PromQL лежит концепция временнЫх рядов, состоящих из набора пар «метрика/значение» с набором меток, которые позволяют детализировать и сегментировать данные по сервисам, инстансам, средам и т. д. Правильное использование PromQL требует понимания модельной базы Prometheus: как устроены данные, как они индексируются и как запросы обрабатываются на этапе выполнения. Этот раздел нацелен на то, чтобы дать прочную базу для построения эффективных наблюдений и для перехода к более сложным сценариям анализа.

Далее мы рассмотрим концептуальные основы, синтаксис селекторов, операторы и базовые функции, которые позволяют формировать первые рабочие дашборды и отчёты по ключевым метрикам.

Обзор концепции модели данных Prometheus и роли PromQL в извлечении информации.
Синтаксис базовых селекторов и диапазонов времени.
Операторы и механизмы сопоставления меток, включая бинарные операции и их семантику.
Базовые функции, агрегации и работа с гистограммами для латентности и пропускной способности.

Основы синтаксиса PromQL и концептуальная модель

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

Селекторы метрик задаются через имя метрики и набор меток.bare-метрика без дополнительных фильтров возвращает все серии с указанной метрикой. Фильтры по меткам задаются с использованием операторов сопоставления: =, !=, =~, !~. Примеры:

cpu_seconds_total{mode="system"}

http_requests_total{job="frontend", status=~"5.."}

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

sum(rate(http_requests_total[5m])) by (service)

Range-векторы выражают наблюдаемые значения за окно времени, например:

rate(http_requests_total[5m])

Этот пример возвращает набор временных рядов, где каждый ряд представляет собой скорость запросов за последние 5 минут для каждого сочетания меток.

Рассматривая семантику идентифицируемых рядов, следует помнить: каждый временной ряд определяется уникальным набором меток, включая, как минимум, имя метрики. Метки могут быть добавлены или отброшены с помощью операций on/ignoring и группировки по label. Это позволяет выполнять точную агрегацию и сравнение по нужному контексту без потери идентичности данных.

Основной концепт: instant vector и range vector.
Селекторы по меткам и их фильтрация.
Группировка по меткам в агрегациях.

Операторы PromQL: арифметика, булевые операции и бинарные операции

PromQL поддерживает широкий набор бинарных операторов, включая арифметику (+, -, *, /, %) и булевые операции (and, or, unless). В контексте временных рядов важна семантика сопоставления меток: бинарные операции применяются к векторам с одинаковыми наборами меток, или требуют явного указания, как сопоставлять метки с помощью модификаторов on/ignoring и группировки по левому/правому вектору (group_left/group_right).

Арифметика над векторам: например, вычисление отношения двух метрик или их суммарная скорость.
Булевые операции: позволяют фильтровать или объединять наборы данных по условиям. Например, A and B вернет пересечение по меткам; A or B - объединение; A unless B - исключение элементов A, которые совпадают по меткам с B.
Модификаторы сопоставления: on(р-ремберем) и ignoring позволяют указать, какие метки должны участвовать в сопоставлении. Это критично при агрегациях по нескольким источникам, где размерность меток может различаться.

Примеры:

rate(app_requests_total[5m]) / rate(total_requests[5m])

Этот запрос иллюстрирует вычисление доли запросов, обрабатываемых конкретным приложением, по отношению к общему объему за окно.

sum(rate(http_requests_total[5m])) by (service)

Здесь мы агрегируем данные по сервису, суммируя значения rate, чтобы получить суммарный показатель по каждому сервису.

cpu_usage_seconds_total{mode!="idle"} unless on(instance) cpu_usage_seconds_total{mode="idle"}

Этот пример демонстрирует одну из тонких практик: исключение «idle» времени на инстансах, где мы хотим видеть только активное использование CPU.

Важно: бинарные операции и модификаторы требуют осмысленного проектирования видимости меток. Неправильное использование can lead to неожиданные результаты, особенно в больших кластерах и когда источники данных внедряют разные наборы меток. Рекомендуется придерживаться соглашений о именовании меток и единообразия в идентификации инстансов и сервисов.

Арифметика над векторами.
Булевые операции и их семантика по меткам.
Модификаторы сопоставления for precise alignment.

Базовые функции PromQL и работа с агрегациями

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

Функции для анализа роста и скорости:

rate(v range-vector) - вычисляет скорость изменения счетчика за диапазон; используется для счетчиков, где значение увеличивается со временем.
irate(v range-vector) - мгновенная скорость изменения счетчика за краткий интервал; полезна для выявления резких изменений.
```
rate(http_requests_total[5m])
```
```
irate(http_requests_total[1m])[5m]
```

Функции для агрегирования по времени:

increase(v range-vector) - суммарное увеличение за интервал; полезно для подсчета прироста за период.
delta(v range-vector) - изменение счетчика или значения за период; применяется к гауд-метрикам.
```
increase(errors_total[1h])
```
```
delta(memory_usage_bytes[10m])
```

Функции по агрегированию по метрикам:

sum_over_time, avg_over_time, min_over_time, max_over_time - агрегируют значения по времени внутри диапазона.
count_over_time - сумма количества точек в диапазоне; применимо для оценок частоты событий.
```
sum_over_time(http_requests_total[10m])
```
```
avg_over_time(cpu_temperature_celsius[15m])
```

Гистограммы и квантильные оценки:

histogram_quantile(φ, rate(metric_bucket[range])) - расчет квантиля на основе гистограммы; ключевой при анализе латентности запросов.
quantile_over_time(φ, metric[range]) - также применяется на аналогичную задачу, но внутри диапазона без преобразования в rate.
```
histogram_quantile(0.95, rate(request_duration_seconds_bucket[5m]))
```

Топики и выборки:

topk(k, v) и bottomk(k, v) - возвращают топ-или нижние k серий по значению.
```
topk(5, sum(rate(http_requests_total[5m])) by (service))
```

Работа с лабораторией меток и преобразования:

label_replace(source_vector, dest_label, replacement, src_label, regex) - перенос значений меток между наборами.
time() - возвращает текущее время UTC; редко нужен, но полезен в тестах.
```
label_replace(instance_metric{job="api"}, "new_label", "$1", "host", "(.*)")
```

Пример полезной комбинации:

quantile_over_time(0.95, rate(http_request_duration_seconds_bucket[5m])) - для расчета 95-го квантиля латентности на интервале.
```
quantile_over_time(0.95, rate(http_request_duration_seconds_bucket[5m])[1h:5m])
```
Важно: выбор функций и паттернов зависит от целей мониторинга. Для стабильно работающих сервисов часто применяют rate + sum by (...) для оценки устойчивости и пропускной способности, а для латентности - histogram_quantile совместно с bucket-метриками. При этом необходимость агрегировать по смысловым тегам (например, по сервисам, средам, регионам) диктует использование sum by (label) или avg by (label) в сочетании с соответствующими диапазонами времени.
Функции для анализа латентности и пропускной способности.
Функции агрегации по времени и по меткам.
Возможности работы с гистограммами и квантилями.

Практические сценарии: типовые запросы для мониторинга

Развитие навыков в PromQL во многом определяется умением переводить бизнес-цели в конкретные запросы. Ниже приведены несколько типовых сценариев, которые часто встречаются в практической работе команд по наблюдению и дегустации сервисов.

Производительность API и латентность:

Определение доли успешных ответов и latency-полы на сервис.

sum(rate(http_requests_total{status!~"5.."}[5m])) by (service)

histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

Эффективность использования ресурсов:

Средняя загрузка CPU по сервисам за 15 минут.
```
avg by (service) (rate(node_cpu_seconds_total{mode!="idle"}[5m]))
```
Использование памяти: параметр доступности.
```
100 * (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)
```

Здоровье и надёжность сервисов:

Доля ошибок среди всех запросов или пиковые 5xx.

sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))

Мониторинг внешних зависимостей:

Доступность базы данных или очередей через экспортёр.
```
sum(rate(mongodb_connections_open_total[5m])) by (instance)
```

Географический и мультиинстансовый анализ:

По регионам, регионами или кластерам.
```
sum(rate(http_requests_total[5m])) by (region)
```

Набор быстрых метрик для дашбордов:

Текущие значения отдельных ключевых метрик.
```
http_requests_total{service="auth"} @ end()
```

Рабочие примеры для Histograms и QoS-показателей:

Латентность операций с использованием histogram bucket:
```
histogram_quantile(0.9, rate(db_query_duration_seconds_bucket[5m]))
```

Интеграция с продвинутыми агрегациями:

Комбинации topk + sum by для выявления топ-объектов по трафику.
```
topk(5, sum(rate(http_requests_total[5m])) by (service))
```
Эти примеры демонстрируют, как можно переходить от общего KPI к конкретным значениям в разрезе сервисов, инстансов и сред, а также как работать с латентностью и устойчивостью системы. Важно помнить о зависимости между выбором окна времени и частотой обновления дашборда: слишком длинные окна могут сглаживать пик и задержки, а слишком короткие - шумно отражать краткосрочные колебания. Практикой является сочетание нескольких стратегий: регулярная проверка ключевых метрик через инстансы и сервисы и параллельно использование квантилей через histogram, чтобы определить критичные сценарии.
Типичные сценарии мониторинга и соответствующие запросы.
Как правильно комбинировать агрегации и фильтры по меткам.
Важность избежания избыточной cardinality и оптимизации запросов.

Архитектура и практики внедрения PromQL в команду

PromQL - инструмент, но его эффективное применение требует процессов и культуры. В контексте технической архитектуры следует рассмотреть следующие аспекты:

Стратегия хранения данных и требования к задержке: Prometheus хранит данные локально в TSDB; агрегирование через PromQL выполняется на лету, поэтому сложные и ресурсоёмкие запросы лучше ограничить к периодическим слотам или использовать агрегированные представления.
Оптимизация запросов: избегайте сложных выражений в реальном времени на больших объёмах данных; применяйте агрегации по меткам и инкрементальные вычисления через rate/increase для счётчиков.
Интеграции и рабочие практики: PromQL тесно интегрирован с Grafana и различными экспортёрами, включая node_exporter и exporters для ваших сервисов. В рамках методологии внедрения рекомендуется разработать единые гайдлайны по формированию запросов, созданию дашбордов и поддержке документирования метрик.
Контроль качества запросов: внедрите чек-листы по читаемости, по ограничению cardinality, по тестированию на выборке сценариев, а также по верификации корректности метрик через synthetic tests.
Безопасность и доступ: ограничение доступа к Prometheus UI и API, аудит запросов и защиту от DoS-атак на уровне агрегаций и запросов.
Подходы к работе с экспорторами и сервис-дискавери: единые правила именования метрик и меток; использование service discovery для автоматического обновления целевых точек без ручного вмешательства.
Роли команд: инженеры по мониторингу, инженеры по данным и DevOps должны сотрудничать над едиными стандартами запросов, чтобы дашборды и алерты отражали реальную ситуацию без избыточной шума.

Key takeaways

PromQL - мощный язык для извлечения и агрегации временных рядов; грамотное использование меток и агрегаций обеспечивает точность и масштабируемость запросов.
Разделение понятий instant vector и range vector критично: мгновенные выражения для текущего состояния, диапазонные - для анализа динамики за окно времени.
Операторы и модификаторы сопоставления позволяют тонко настраивать, какие наборы меток участвуют в вычислениях; неправильная настройка может привести к искажению результатов.
Базовые функции PromQL покрывают частые сценарии: rate/increase для счетчиков, avg/sum над временем, квантиля и гистограммы для латентности и качества обслуживания.
Практические сценарии мониторинга часто строятся на сочетании rate/sum by (...) и histogram_quantile; избегайте чрезмерного расходования ресурсов на слишком длинные окна и высокую кардинальность меток.
Интеграция с инструментами визуализации (например, Grafana) и процессов внедрения требует общих стандартов именований, документации и тестирования запросов.
Регулярно выполняйте ревизии запросов и оптимизируйте их под реальный спрос и размер данных, чтобы поддерживать адаптивность и отклик инструментов мониторинга.

FAQ

Что такое instant vector и range vector в PromQL, и когда их использовать?

Instant vector содержит значения в конкретный момент времени для каждого временного ряда. Range vector содержит значения за диапазон времени. Используйте instant vector для текущей картины и агрегирования по меткам, а range vector - для анализа динамики и вычисления rate, increase и других функций по времени.

Как выбрать подходящие метки для агрегации?

Выбор меток должен отражать ту бизнес-аспекты, по которым необходимо наблюдать поведение системы (service, instance, region, job и т. д.). Важно избегать излишней/Cardinality‑детерминированности: слишком много уникальных меток приводят к росту нагрузки на хранение и вычисления.

В чем принципиальная разница между rate и increase?

rate рассчитывает скорость изменения счетчика за окно (часто используем для пропорций и долей), тогда как increase возвращает суммарное увеличение за окно - более естественно для подсчета общего числа событий за период.

Что такое histogram_quantile и когда его использовать?

histogram_quantile вычисляет квантиль на основе гистограммы, полученной из bucket-метрик. Это ключевой инструмент для оценки латентности операций и качества обслуживания по различным квантилям (например, 95-й или 99-й процентиль).

Какие рекомендации по производительности запросов в PromQL можно дать?

Предпочитайте простые выражения и явные группировки by label; избегайте wildcard-меток и слишком длинных цепочек евроопераций; используйте rate/increase для счетчиков, а histogram-вычисления - только там, где детальная латентность критична; тестируйте запросы на реальных наборах данных и в условиях пиковых нагрузок.

Какую роль играет модификатор on/ignoring в бинарных операциях?

Они позволяют управлять тем, какие метки участвуют в сопоставлении при выполнении бинарной операции между двумя векторами. Неправильное применение может привести к неверной агрегации или дублированию строк. Их следует использовать для явной конфигурации соответствия между набором меток.

Какие виды интеграции PromQL важны для производственной среды?

Интеграция с Grafana или аналогичными панелями мониторинга, экспортёры для приложений и инфраструктуры (например, node_exporter), а также сервис-дискавери для автоматического обновления целевых точек. Важно иметь единообразные практики документирования и тестирования запросов в ваших дашбордах.

Как избежать чрезмерной кардинальности в метках?

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

Какие типичные ошибки встречаются при написании PromQL-запросов?

Неправильное использование группировок и меток, несогласованность в именовании метрик, злоупотребление сложными выражениями в реальном времени и игнорирование cardinality-эффекта. Эти ошибки приводят к неверным выводам, задержкам и перегрузке сервера.

Какие ресурсы и примеры можно использовать для дальнейшего обучения PromQL?

Официальная документация Prometheus по PromQL; открытые примеры дашбордов и запросов в графических панелях, например, в Grafana; учебные материалы по экспортёрам и практики по мониторингу микросервисов. При этом важно адаптировать примеры под ваши сервисы и архитектуру, чтобы запросы отражали реальную бизнес-цель.

Концептуальная глубина, практические примеры и принципы внедрения PromQL в этой главе призваны заложить прочную базу для последующих тем курса: от расширенной аналитики и сложной корреляции до построения комплексных систем мониторинга и автоматизированной диагностики.

← Предыдущая статья

Метрики, SLO и SRE: SLIs, SLOs, их связь с бизнес-целями

Следующая статья →

Расчеты временных рядов: rate, increase, delta и оконные функции