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

Короткий ответ

Простейший PromQL-запрос — это просто имя метрики, например http_requests_total, которое вернёт все текущие временные ряды с этим именем; чтобы выбрать конкретный ряд, к имени добавляют фильтр по labels в фигурных скобках, например http_requests_total{job="api", status="500"}.

Как это работает подробнее

каждая метрика в Prometheus — это набор временных рядов, различающихся комбинацией labels (пар ключ-значение). Запрос без фигурных скобок возвращает все ряды с данным именем; оператор = внутри {} фильтрует по точному совпадению значения label, != — по несовпадению, =~ и !~ — по регулярному выражению.

Пример кода

query.promqlКопировать

# Все ряды метрики
http_requests_total
# Только 5xx-ошибки сервиса checkout в проде
http_requests_total{service="checkout", status=~"5..", env="prod"}

Что использовать на практике

• Практика. при построении дашборда или алерта почти всегда нужно сузить выборку до конкретного сервиса/окружения, иначе график смешает данные разных инстансов. Полезно сначала посмотреть доступные labels метрики через вкладку "Metrics explorer" в Grafana или curl к /api/v1/series, а затем писать точный фильтр.
• Практика. Выполнение второго запроса в Prometheus UI (/graph) вернёт только ряды, где label status начинается с 5 (регулярное выражение 5..), что подтверждает корректность фильтрации по regex для диапазона кодов ошибок.

Подводные камни

• Частые ошибки. забывать, что без фильтра по labels в выборку попадут все окружения (включая staging) и график станет бессмысленным; путать =~ (regex-match) с = (точное совпадение) и получать пустой результат при наличии спецсимволов в значении; не знать, что лейблы job и instance добавляются Prometheus автоматически при scrape и всегда доступны для фильтрации.