Документация Grafana Документация GlaberGraph Источники данных Prometheus Аннотации

Аннотации Prometheus

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

Общую информацию об аннотациях см. в разделе Аннотирование визуализаций.

Перед началом

Перед созданием аннотаций Prometheus убедитесь, что у вас есть:

• Настроенный источник данных Prometheus в Grafana
• Метрики в Prometheus, которые представляют события, которые вы хотите аннотировать
• Доступ на чтение к экземпляру Prometheus

Создание запроса аннотации

Чтобы добавить аннотацию Prometheus на ваш дашборд:

1. Перейдите к дашборду, который хотите обновить, и нажмите Edit.
2. Нажмите значок Add new element (синий знак плюс).
3. Нажмите Annotation query.
4. Введите имя для запроса аннотации.
5. Если вы не хотите сразу использовать запрос аннотации, снимите флажок Enabled.
6. Выберите цвет для маркеров событий аннотации.
7. Выберите опцию в раскрывающемся списке Show annotation controls in, чтобы управлять тем, где на дашборде отображается аннотация.
8. Выберите опцию в раскрывающемся списке Show in, чтобы управлять тем, на каких панелях отображается аннотация.
9. Нажмите Open query editor, чтобы открыть диалоговое окно Annotation Query.
10. Выберите ваш источник данных Prometheus в раскрывающемся списке Data source.
11. Введите выражение PromQL в поле запроса.
12. Установите Min step, чтобы управлять плотностью аннотаций (больший шаг означает меньше аннотаций).
13. Настройте сопоставления полей, чтобы управлять тем, что появляется во всплывающей подсказке аннотации.
14. (Необязательно) Нажмите Test annotation query, чтобы убедиться, что запрос работает правильно.
15. Нажмите Close, когда завершите настройку запроса.
16. Нажмите Save.
17. (Необязательно) Введите описание внесённых изменений.
18. Нажмите Save.
19. Нажмите Exit edit.

Как работают аннотации Prometheus

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

• Grafana выполняет запрос PromQL как запрос диапазона за временное окно дашборда.
• Каждая возвращённая точка данных создаёт аннотацию. Автоматической фильтрации нулевых значений нет. Если вам нужны аннотации только в определённые моменты, ваше выражение PromQL должно отфильтровать результаты (например, используя > 0 или метрику ALERTS).
• Grafana использует конфигурацию сопоставления полей, чтобы определить, какой текст, заголовок и теги отображать для каждой аннотации.
• Если запрос возвращает несколько временных рядов, каждый ряд создаёт свой собственный набор аннотаций.

Сопоставления полей

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

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

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

В следующих примерах показаны распространённые шаблоны аннотаций с Prometheus.

Аннотации на основе алертов с использованием ALERTS

Самый распространённый и надёжный способ создания аннотаций Prometheus. Prometheus автоматически генерирует метрику ALERTS для всех настроенных правил алертинга.

promql Copy

ALERTS{alertstate="firing"}

Это создаёт аннотацию на каждом интервале шага, где срабатывает алерт. Метрика ALERTS включает такие метки, как:

• alertname: имя правила алертинга
• alertstate: либо firing, либо pending
• любые метки, определённые в правиле алертинга

Чтобы ограничиться конкретными алертами или уровнями серьёзности:

promql Copy

ALERTS{alertname="HighCPUUsage", severity="critical"}

Настройте сопоставления полей:

• Text: alertname (отображает имя алерта при наведении)
• Tags: severity (позволяет фильтровать по серьёзности)

Аннотации перезапуска служб

Отображайте аннотации при перезапуске процесса. Функция changes() определяет, когда значение изменяется, а > 0 гарантирует, что аннотации появляются только в момент изменения:

promql Copy

changes(process_start_time_seconds{job="myservice"}[5m]) > 0

Аннотации развёртываний

Если вы отслеживаете развёртывания, отправляя метрику временной метки через Pushgateway или правило записи:

promql Copy

changes(deployment_timestamp_seconds{environment="production"}[10m]) > 0

Настройте сопоставления полей:

• Text: environment (показывает, какая среда была развёрнута)
• Tags: environment

Аннотации пересечения порогов

Отображайте аннотации, когда доступная память падает ниже 10%:

promql Copy

node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes < 0.1

Аннотации событий масштабирования

Отображайте аннотации, когда количество запущенных pod изменяется:

promql Copy

changes(kube_deployment_status_replicas{deployment="my-app"}[5m]) > 0

Аннотации всплесков ошибок

Отображайте аннотации, когда частота ошибок превышает порог:

promql Copy

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

Это создаёт аннотации, когда частота ошибок превышает 5%.

Аннотации изменения версии или сборки

Если вы предоставляете метаданные сборки с помощью метрики, такой как build_info (часто встречается в службах на Go), аннотируйте при изменении версии:

promql Copy

changes(build_info{job="myservice"}[10m]) > 0

Настройте сопоставления полей:

• Text: version (показывает новую версию во всплывающей подсказке аннотации)
• Tags: job

Если ваша метрика информации о сборке использует метку version (например, build_info{version="1.2.3"}), всплывающая подсказка аннотации отображает развёрнутую версию.

Управление плотностью аннотаций

Настройка Min step управляет тем, сколько точек данных возвращает запрос, что напрямую влияет на то, сколько аннотаций появляется. Больший шаг означает меньше аннотаций:

• Min step 1m: до одной аннотации в минуту (хорошо для коротких диапазонов времени).
• Min step 5m: до одной аннотации каждые 5 минут (хорошо для дашбордов на день).
• Min step 1h: до одной аннотации в час (хорошо для дашбордов на неделю).

Если ваш дашборд показывает слишком много маркеров аннотаций, увеличьте Min step или добавьте более конкретные фильтры в ваш запрос.

Использование переменных шаблонов в аннотациях

Вы можете использовать переменные шаблонов в ваших запросах аннотаций, чтобы фильтровать аннотации на основе выбора переменных дашборда:

promql Copy

ALERTS{alertstate="firing", instance=~"$instance"}

promql Copy

changes(process_start_time_seconds{job="$job"}[5m]) > 0

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

Аннотации диапазона

Аннотации диапазона отображаются как затенённые области, а не вертикальные линии, представляя события с длительностью. Чтобы создать аннотации диапазона, результат запроса должен включать сопоставление поля TimeEnd.

Поскольку PromQL изначально не возвращает пары начального/конечного времени, аннотации диапазона с Prometheus ограничены сценариями, где у вас есть отдельные метрики для начального и конечного времени (например, через правила записи или пользовательские метрики, отправленные в Pushgateway). Для большинства случаев использования точечные аннотации (с использованием примеров на этой странице) — практичный подход.

Если ваши аннотации не появляются или вы сталкиваетесь с ошибками, см. раздел Устранение неполадок источника данных Prometheus.