Документация Grafana Документация GlaberGraph Источники данных Prometheus Переменные шаблонов

Переменные шаблонов Prometheus

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

Введение в шаблонизацию и переменные шаблонов см. в разделах Шаблонизация и Добавление переменных и управление ими.

Типы переменных запросов

Переменные запросов обращаются к Prometheus, чтобы заполнить значения раскрывающихся списков. При создании переменной запроса выберите источник данных Prometheus и тип запроса:

Подробности об именах метрик, именах меток и значениях меток см. в модели данных Prometheus.

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

Label values (заполнение раскрывающегося списка всеми jobs):

1. Создайте новую переменную с Type: Query.
2. Выберите ваш источник данных Prometheus.
3. Установите Query type в Label values.
4. Установите Label в job.
5. Оставьте Metric пустым, чтобы запрашивать по всем метрикам.

Раскрывающийся список переменной теперь показывает все уникальные значения метки job.

Label values (отфильтровано по метрике):

Установите Label в instance, а Metric — в node_cpu_seconds_total, чтобы показывать только экземпляры, сообщающие метрики ЦП.

Metrics (поиск доступных метрик по шаблону):

Установите Query type в Metrics и введите http_.*_total в поле Metric, чтобы заполнить раскрывающийся список всеми метриками счётчиков HTTP.

Query result (динамическая фильтрация top-N):

Установите Query type в Query result и введите:

promql Copy

query_result(topk(5, sum(rate(http_requests_total[$__range])) by (instance)))

Установите Regex в /"([^"]+)"/, чтобы извлечь значения instance из результата.

Установите Refresh в On time range change, чтобы топ-5 экземпляров обновлялись при изменении диапазона времени дашборда.

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

Параметры выбора

• Multi-value: позволяет выбирать несколько значений сразу. Grafana соединяет их вертикальной чертой (|) для сопоставления по регулярному выражению.
• Include All option: добавляет опцию «All», которая выбирает все значения. В сочетании с multi-value это генерирует регулярное выражение вида value1|value2|value3.

Пример с multi-value:

promql Copy

rate(http_requests_total{job=~"$job"}[$__rate_interval])

Использование переменных интервалов и диапазонов

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

Подробности см. в разделе Глобальные встроенные переменные.

Функция label_values (тип Classic query) не поддерживает эти переменные. Используйте вместо этого тип Query result с query_result():

promql Copy

query_result(max_over_time(up{job="$job"}[${__range_s}s]) == 1)

Установите Refresh переменной в On time range change, чтобы обновлять значения при изменении диапазона времени.

Использование $__rate_interval

$__rate_interval — это специфичная для Grafana переменная, предназначенная для использования с rate() и increase(). Она гарантирует достаточно большое окно диапазона, чтобы захватить как минимум четыре образца сбора, предотвращая разрывы или неточности в результатах.

Всегда используйте $__rate_interval вместо фиксированного интервала или $__interval:

promql Copy

rate(http_requests_total[$__rate_interval])

А не:

promql Copy

rate(http_requests_total[5m])       # breaks at different zoom levels
rate(http_requests_total[$__interval])  # can be too small for rate()

Как вычисляется $__rate_interval

Copy

max($__interval + scrape_interval, 4 * scrape_interval)

Где scrape_interval — это:

1. Настройка Min step для запроса, если она задана.
2. В противном случае — настройка Scrape interval источника данных (в разделе Interval behavior в конфигурации источника данных).

На min interval уровня панели влияет настройка разрешения, и она не учитывается в этом вычислении.

Правильная настройка $__rate_interval

Чтобы $__rate_interval давала надёжные результаты, интервал сбора должен соответствовать вашей фактической конфигурации сбора Prometheus:

1. Откройте конфигурацию источника данных Prometheus.
2. В разделе Interval behavior установите Scrape interval в соответствии с scrape_interval в вашем файле конфигурации Prometheus (например, 30s или 1m).
3. Если разные цели имеют разные интервалы сбора, установите интервал сбора источника данных в наибольший используемый интервал или используйте Min step для запроса, чтобы переопределить его на конкретных панелях.

Распространённые подводные камни

• Отсутствующая или неверная настройка интервала сбора: если интервал сбора источника данных оставлен по умолчанию 15s, но ваш фактический интервал сбора Prometheus — 60s, $__rate_interval вычисляет слишком маленькое окно. Это приводит к тому, что rate() не возвращает данных, потому что в окне недостаточно точек данных.

• Разные значения в режиме редактирования и на дашборде: при редактировании запроса панель отображается на всю ширину. На дашборде панель может быть уже, что увеличивает $__interval и, следовательно, $__rate_interval. Запросы, работающие в режиме редактирования, могут давать другие результаты (или разрывы) на дашборде.

• Источники данных с включённым LBAC: источники данных, использующие управление доступом на основе меток (LBAC), могут не наследовать настройку интервала сбора от родительского источника данных. Установите Min step явно на каждой панели запроса, чтобы обеспечить правильное вычисление $__rate_interval.

• Правила записи с фиксированными интервалами: если вы используете $__rate_interval в запросе правила записи, интервал зависит от контекста вычисления. Для правил записи используйте фиксированный интервал (например, [5m]) вместо $__rate_interval.

Для устранения проблем с $__rate_interval см. Rate interval не возвращает данных или возвращает некорректные значения.

Дополнительный контекст см. в статье $__rate_interval for Prometheus rate queries that just work.

Синтаксис переменных

Источник данных Prometheus поддерживает три синтаксиса переменных:

Переменная фильтров

Prometheus поддерживает тип переменной Filters (ранее называвшийся «ad hoc filters»), который позволяет зрителям дашборда динамически добавлять фильтры меток без редактирования запросов.

Чтобы настроить переменную Filters:

1. Создайте новую переменную с Type: Filters.
2. Выберите ваш источник данных Prometheus.
3. Сохраните дашборд.

После добавления переменной в верхней части дашборда появляется панель фильтров. Зрители могут добавлять фильтры, выбирая метку, оператор (=, !=, =~, !~) и значение. Grafana автоматически применяет эти фильтры ко всем запросам Prometheus на дашборде.

Пример: зритель добавляет фильтр namespace = production. Все запросы на дашборде теперь включают {namespace="production"} без каких-либо изменений запросов.

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

• Редактор запросов: используйте переменные в запросах PromQL.
• Аннотации: используйте переменные шаблонов в запросах аннотаций.
• Устранение неполадок: решайте проблемы запросов, связанные с переменными.