Аннотации

График показывает резкий рост ошибок. Во сколько это случилось? В 14:35. А рядом с графиком — пометка «Deploy v2.3.1 в production», поставленная в 14:33. Причинно-следственная связь установлена за две секунды, без дебага.

Аннотации — это метки на временной шкале. Они отвечают на вопрос «Что происходило в этот момент?»:

• Релизы приложений.
• Сбои в инфраструктуре.
• Запуски ручных тестов.
• Любые изменения, о которых нужно помнить при аналитике.

Источники аннотаций

Ручные

Нажал Ctrl+Click на графике или кнопку «аннотация» в интерфейсе — ввёл текст. Просто и быстро. Хорошо для мелких пометок.

Через API

curl -X POST https://grafana.company.com/api/annotations \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hotfix #8472 deployed",
    "tags": ["deploy", "production"],
    "time": 1723632000000
  }'

Интегрируете в CI/CD — и каждый деплой автоматически отметит себя на всех дашбордах.

Из Prometheus

changes(kube_deployment_status_observed_generation[1m]) > 0

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

Из Loki

{app="nginx"} |= "error" | rate[5m] > 10

Как только частота ошибок превышает порог, аннотация наносит метку. На графике сразу видно: всплеск ошибок произошёл тогда-то, длился столько-то.

Из MySQL

Подключились к таблице релизов в корпоративной БД — и на графике видны даты версий приложения, прямо из production-репозитория.

Color mapping

Аннотациям можно назначать цвета. Например, deploy — синий, ошибка — красный, maintenance — серый. Сразу видно категорию события, даже не вчитываясь.