Документация Grafana Документация GlaberGraph Источники данных Prometheus Редактор запросов

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

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

Вы можете получить доступ к редактору запросов со страницы Explore или с любой панели дашборда, нажав на заголовок панели и выбрав Edit. Общую документацию по запросам к источникам данных в Grafana см. в разделе Запрос и преобразование данных. Дополнительную информацию о PromQL см. в разделе Querying Prometheus.

Редактор запросов имеет два режима:

• Режим Builder: визуальный интерфейс для построения запросов без написания PromQL напрямую.
• Режим Code: текстовый редактор с автодополнением для написания PromQL напрямую.

Grafana синхронизирует оба режима, позволяя переключаться между ними. Grafana также отображает предупреждающее сообщение, если обнаруживает проблему с запросом при переключении режимов.

Параметры запроса

Следующие параметры доступны как в режиме Builder, так и в режиме Code. Они управляют тем, как выполняется запрос и как отображаются результаты.

Легенда

Управляет отображаемым именем для временных рядов в легенде панели.

• Auto: отображает только уникальные метки, скрывая метки, общие для всех возвращённых рядов. Это даёт более чистые легенды, когда многие ряды имеют одинаковые метки.
• Verbose: отображает все имена меток для каждого ряда.
• Custom: позволяет определить легенду с помощью шаблонов меток. Например, {{hostname}} заменяется значением метки hostname. Чтобы переключиться на другой режим легенды, очистите поле ввода и щёлкните вне него.

Min step

Задаёт минимальный интервал между точками данных, возвращаемыми запросом. Например, установка 1h означает, что данные возвращаются как минимум с часовыми интервалами. Эта настройка поддерживает макросы $__interval и $__rate_interval.

Format

Определяет, как результаты запроса интерпретируются и отображаются на панели.

• Time series: формат по умолчанию. Возвращает данные в виде привязанных ко времени рядов, подходящих для панелей-графиков.
• Table: отображает данные в табличном формате. Работает только в панели Table.
• Heatmap: отображает метрики типа гистограмм в панели Heatmap, преобразуя кумулятивные гистограммы в обычные и сортируя ряды по границе корзины.

Type

Определяет тип запроса.

• Both: по умолчанию. Выполняет как запрос Range, так и запрос Instant и возвращает объединённые результаты.
• Range: возвращает набор временных рядов, где каждый ряд включает несколько точек данных за выбранный диапазон времени. Используйте это для визуализаций-графиков (линии, столбцы, точки, с накоплением).
• Instant: возвращает одну точку данных на ряд (самое последнее значение в выбранном диапазоне времени). Используйте это для панелей stat, таблиц или индикаторов. Чтобы визуализировать результаты instant-запроса на панели временных рядов, добавьте переопределение поля со свойством Transform, установленным в Constant. Дополнительную информацию см. в разделе Опция Transform для временных рядов.

Экземпляры (Exemplars)

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

Режим Builder

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

Режим Builder содержит следующие компоненты:

• Kick start your query: нажмите, чтобы просмотреть предопределённые шаблоны операций, которые помогают быстро строить запросы с несколькими операциями:

  • Rate query starters
  • Histogram query starters
  • Binary query starters

  Нажмите стрелку рядом с каждым, чтобы увидеть доступные параметры.

• Explain: включите, чтобы отобразить пошаговое объяснение всех компонентов и операций запроса.

Выбор метрики

• Metric: выберите метрику в раскрывающемся списке. Источник данных предоставляет доступные метрики на основе выбранного диапазона времени. Вы можете вводить текст для поиска и фильтрации списка. Нажмите значок книги, чтобы открыть Metrics explorer.
• Label filters: выберите метки и значения для фильтрации метрики. Используйте кнопку +, чтобы добавить фильтры, и кнопку x, чтобы удалить их. Когда метрика выбрана, источник данных запрашивает доступные метки и их значения с сервера.

Добавление операций

Нажмите + Operations, чтобы добавить операции в ваш запрос. Редактор запросов группирует операции в следующие категории:

• Агрегации: sum, avg, count, min, max и т. д.
• Функции диапазона: rate, increase, irate, avg_over_time и т. д.
• Функции: abs, ceil, histogram_quantile и т. д.
• Бинарные операции: арифметические операторы и операторы сравнения.
• Тригонометрические функции: acos, asin, atan и т. д.
• Функции времени: time, timestamp, day_of_week и т. д.

Все операции отображают параметры функции под заголовком операции. Некоторые операции позволяют применять определённые метки (например, предложения by или without).

Если вы добавляете операцию способом, который создал бы недопустимый запрос, редактор запросов автоматически помещает её в правильную позицию, чтобы сохранить допустимую структуру запроса.

Подсказки

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

Metrics explorer

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

Под Additional Settings доступны следующие параметры:

• Include description in search: поиск как по имени, так и по описанию.
• Include results with no metadata: включить метрики, у которых отсутствуют метаданные типа или описания.
• Disable text wrap: отключить перенос текста для длинных имён метрик.
• Enable regex search: фильтровать имена метрик по регулярному выражению, что использует дополнительный вызов API.

Режим Code

Режим Code предназначен для опытных пользователей Prometheus, которые предпочитают писать PromQL напрямую. Дополнительную информацию о PromQL см. в разделе Querying Prometheus.

Режим Code предоставляет:

• Автодополнение: предлагает метрики, метки, функции, агрегации и ключевые слова по мере ввода. Раскрывающийся список включает документацию для предложенных элементов, где она доступна.
• Подсветка синтаксиса: цветовое кодирование синтаксиса PromQL для удобства чтения.
• Metrics browser: нажмите стрелку рядом с Metrics browser, чтобы открыть его.

Metrics browser

Metrics browser помогает строить базовые запросы, исследуя доступные метрики и метки.

1. Шаг 1: выберите метрику. Браузер сужает доступные метки до тех, которые применимы к метрике.
2. Шаг 2: выберите одну или несколько меток.
3. Шаг 3: выберите значения для каждой метки, чтобы сузить область запроса.
4. Шаг 4: выберите действие:
   • Use query: вставить селектор в редактор запросов.
   • Use as rate query: вставить селектор, обёрнутый в rate(...[$__rate_interval]).
   • Validate selector: проверить, что селектор допустим, и отобразить количество соответствующих рядов.
   • Clear: сбросить ваши выборы.

Все списки в Metrics browser включают поле поиска. В разделе Values одно поле поиска фильтрует по всем выбранным меткам.

Распространённые шаблоны запросов

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

Частота запросов на службу

Вычислите количество HTTP-запросов в секунду с разбивкой по службе:

promql Copy

sum(rate(http_requests_total[$__rate_interval])) by (service)

Шаги в режиме Builder: выберите http_requests_total → добавьте операцию Range functions > Rate → добавьте операцию Aggregations > Sum → установите метку by в service.

Процент ошибок

Вычислите процент запросов, вернувших ошибки 5xx:

promql Copy

sum(rate(http_requests_total{status=~"5.."}[$__rate_interval])) / sum(rate(http_requests_total[$__rate_interval])) * 100

Квантиль гистограммы (задержка p95)

Вычислите 95-й процентиль длительности запроса по метрике гистограммы:

promql Copy

histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[$__rate_interval])) by (le))

Шаги в режиме Builder: выберите http_request_duration_seconds_bucket → добавьте Range functions > Rate → добавьте Aggregations > Sum с меткой by le → добавьте Functions > Histogram quantile со значением 0.95.

Агрегация по метке (использование ЦП на экземпляр)

Вычислите средний процент использования ЦП, сгруппированный по экземпляру:

promql Copy

100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[$__rate_interval])) * 100)

Выражения с несколькими запросами (процент доступной памяти)

Используйте несколько запросов и выражений для вычисления производных значений. В редакторе запросов добавьте несколько запросов (A, B) и математическое выражение (C):

Запрос A (общая память):

promql Copy

node_memory_MemTotal_bytes

Запрос B (доступная память):

promql Copy

node_memory_MemAvailable_bytes

Выражение C (процент доступной памяти). Чтобы добавить его, нажмите + Expression и выберите Math:

Copy

$B / $A * 100

Установите запросы A и B в Type: Instant и скройте их от визуализации (нажмите значок глаза). Отображайте только выражение C.

Совместимый с алертами запрос (цель недоступна)

Простой запрос алерта, который срабатывает, когда цель сбора недоступна:

promql Copy

up{job="my-service"} == 0

Использование query inspector

Query inspector помогает отлаживать запросы, возвращающие неожиданные результаты или никаких данных. Чтобы открыть его:

1. Нажмите Query inspector в представлении редактирования панели (под редактором запросов).
2. Просмотрите следующие вкладки:
   • Query: показывает точный запрос, отправленный в Prometheus, включая вычисленное выражение PromQL, диапазон времени и интервал шага. Используйте это, чтобы убедиться, что переменные шаблонов разрешились правильно.
   • Data: показывает сырые данные ответа. Если пусто, ваш запрос не сопоставился ни с одним рядом.
   • Stats: показывает тайминги запроса и размер ответа.

Распространённые шаги отладки:

1. Данные не возвращаются: проверьте вкладку Query, чтобы увидеть, не разрешились ли переменные шаблонов в пустые значения. Попробуйте запрос напрямую во встроенном браузере выражений Prometheus (/graph), чтобы исключить проблемы, специфичные для Grafana.
2. Меньше рядов, чем ожидалось: проверьте, не слишком ли ограничительны ваши фильтры меток. Удаляйте фильтры по одному, чтобы изолировать тот, который исключает данные.
3. «Too many data points» или тайм-аут: уменьшите диапазон времени, увеличьте Min step или добавьте агрегации, чтобы уменьшить кардинальность. См. Запрос данных с высокой кардинальностью.

Запрос данных с высокой кардинальностью

Метрики с высокой кардинальностью (те, у которых много уникальных комбинаций меток) могут вызывать тайм-ауты запросов или превышение лимитов памяти при запросе за длительные диапазоны времени. Следуйте этим практикам, чтобы эффективно запрашивать данные с высокой кардинальностью:

• Сначала агрегируйте, затем фильтруйте: используйте sum(), avg() или count(), чтобы уменьшить количество рядов перед применением других операций. Например, sum(rate(metric[5m])) by (service) намного дешевле, чем запрос всех отдельных рядов уровня Pod.
• Используйте правила записи для повторяющихся запросов: если панель дашборда запрашивает одно и то же дорогостоящее выражение при каждой загрузке, создайте правило записи Prometheus, чтобы предварительно вычислить результат.
• Ограничивайте область с помощью переменных шаблонов: используйте переменные шаблонов дашборда, чтобы выбрать конкретный namespace, cluster или job, а не запрашивать все метки сразу.
• Увеличьте Min step для обзорных панелей: для панелей, показывающих тренды за дни или недели, установите более высокий Min step (например, 5m или 15m), чтобы уменьшить количество запрашиваемых точек данных.
• Задайте Max data points: используйте параметр запроса Max data points, чтобы ограничить разрешение для широких диапазонов времени.
• Используйте Adaptive Metrics (Grafana Cloud): Adaptive Metrics автоматически снижает кардинальность метрик, которые не запрашиваются с полным разрешением.

Если ваши запросы достигают лимитов памяти или образцов, см. Превышен лимит памяти для запросов с высокой кардинальностью.

Ожидаемое поведение PromQL

Следующее поведение часто ошибочно воспринимается как ошибки, но это ожидаемое поведение Prometheus.

increase() возвращает дробные значения для целочисленных счётчиков

increase() использует линейную интерполяцию для оценки прироста за указанное временное окно. Поскольку временные метки сбора редко точно совпадают с границами окна, результат интерполируется, что даёт дробные значения даже для целочисленных счётчиков.

Это ожидаемо. Если вам нужны целочисленные результаты, оберните выражение в ceil() или floor():

promql Copy

ceil(increase(http_requests_total[5m]))

rate() выглядит растущим со временем

Если rate() показывает постоянно растущее значение вместо стабильной скорости в секунду, наиболее частая причина — несколько экземпляров, записывающих в один и тот же временной ряд без уникальных различающих меток. Prometheus объединяет их в один ряд с искусственно растущим счётчиком.

Чтобы исправить это, убедитесь, что у каждой цели сбора есть уникальные метки (например, instance, pod или node). Затем агрегируйте явно:

promql Copy

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

Если вы видите это после развёртывания или события масштабирования, убедитесь, что ваше обнаружение служб назначает уникальные метки instance каждой цели.

Всплески сброса счётчиков после перезапусков pod

Когда отслеживаемый процесс перезапускается, его счётчики сбрасываются в ноль. Prometheus обрабатывает это с помощью обнаружения сброса счётчиков: rate() и increase() учитывают сбросы и не дают отрицательных значений. Однако вы всё ещё можете увидеть кратковременный всплеск в точке сброса, потому что первый сбор после перезапуска сообщает полное значение счётчика, накопленное с момента перезапуска.

Чтобы минимизировать визуальное влияние:

• Используйте rate() за окно, охватывающее несколько интервалов сбора (например, $__rate_interval), чтобы всплеск усреднялся.
• Для критически важных дашбордов примените сглаживание с более длинным векторным диапазоном или используйте avg_over_time() поверх rate().
• Если вы видите большие всплески от частых перезапусков pod, исследуйте частоту перезапусков, а не пытайтесь скрыть всплески в запросах.

Кардинальность меток вызывает ошибки «too many time series»

Если добавление фильтра метки не уменьшает количество результатов, возможно, у ваших метрик есть метки с высокой кардинальностью (такие как request_id или user_id). Используйте страницу состояния TSDB Prometheus (/tsdb-status) или Metrics explorer Grafana, чтобы выявить комбинации меток с высокой кардинальностью, затем либо удалите ненужные метки во время сбора, либо используйте агрегацию в ваших запросах.

Связанные ресурсы

• Переменные шаблонов: используйте переменные, такие как $namespace или $job, для создания динамических, многократно используемых дашбордов.
• Аннотации: накладывайте события Prometheus на ваши панели.
• Алертинг: создавайте правила алертинга на основе ваших запросов Prometheus.
• Устранение неполадок: решайте распространённые ошибки запросов и проблемы производительности.