Guides: Маркеры событий (аннотации)

Mon, 01 Jan 0001 00:00:00 +0000

На этой странице:

Что это такое
Быстрый старт
Зачем это нужно
Ключевые понятия
Готовые примеры
Справочник API
Совместимость с Grafana
Хранение и доступ

Что это такое

Доступно с версии 201

Grafana-совместимый API маркеров событий (/api/annotations) для записи релизов, деплоев, изменений и инцидентов и их отображения на дашбордах.

Маркер события (аннотация) — это отметка во времени поверх графиков метрик:

точечный маркер — вертикальная линия (событие в один момент);
интервальный маркер — закрашенная область (событие с длительностью).

Метрики показывают, что произошло (выросло время отклика, пошли ошибки), но не отвечают, почему именно в этот момент. Маркеры добавляют недостающий слой контекста: «время отклика подскочило сразу после релиза v2.4.1» или «провал трафика — это плановые работы, а не авария».

События записываются простым HTTP-запросом из CI/CD-пайплайнов, скриптов и сторонних систем.

Быстрый старт

Отметить релиз — один запрос:

curl -X POST "https://${PROTO_BACKEND_URL}/api/annotations" \
 -H "Content-Type: application/json" \
 -d '{"text": "Релиз payment_bank v2.4.1", "tags": ["release"], "type": "RELEASE", "service": "payment_bank"}'

В ответ вернётся идентификатор созданного маркера:

{ "id": "0a4e7c8b-1f2d-4a3e-9b8c-2d1e0f3a4b5c", "message": "Annotation added" }

Готово — событие записано и доступно для отображения на дашбордах. Аутентификация не требуется (см. Хранение и доступ); PROTO_BACKEND_URL указывается без префикса https://.

Зачем это нужно

Один маркер на графике мгновенно отвечает на первый вопрос при разборе сбоя — «что изменилось прямо перед этим?». Большинство инцидентов в проде вызвано именно изменениями (деплой или конфигурация), поэтому такая корреляция напрямую сокращает время восстановления (MTTR).

Сценарий	Что отмечаем	Что это даёт заказчику
Релизы и деплои	Версия, коммит, время выката	Видно, что всплеск ошибок совпал с релизом → быстрый откат и точный виновник
Инциденты и аварии	Период деградации (интервал)	Готовая хронология для постмортема и аудита
Плановые работы	Окно техработ (интервал)	Падение трафика не путают с аварией и не засчитывают как нарушение SLO
Изменения конфигурации	Feature-флаг, масштабирование, миграция БД	Объясняет «загадочные» деградации, не связанные с релизом кода
Бизнес-события	Кампания, распродажа, рассылка	Всплеск нагрузки выглядит объяснимым, а не аномальным

Дополнительно маркеры дают контекст дежурному без «археологии» (не нужно искать по Git, чатам и CI-логам) и при длительном хранении служат журналом изменений в проде.

Ключевые понятия

Точечный маркер — событие в один момент времени (по умолчанию). Время задаётся полем time.
Интервальный маркер — событие с длительностью. Создаётся добавлением timeEnd и отображается закрашенной областью.
Глобальное событие — поле service не задано. Относится ко всей платформе и видно на дашборде любого сервиса. Подходит для платформенных релизов и общих работ.
Событие сервиса — поле service задано. Видно только в контексте этого сервиса, не зашумляя остальные дашборды.
Теги (tags) — метки для фильтрации (release, deployment, change, incident, env:production). По ним дашборды отбирают, какие события показывать.
Тип (type) — категория маркера, например RELEASE.

Готовые примеры

Скопируйте подходящий шаблон в свой пайплайн или скрипт. Время указывается в миллисекундах эпохи (Unix-время × 1000).

Релиз конкретного сервиса (со ссылкой на сборку — в text допустима HTML-разметка):

curl -X POST "https://${PROTO_BACKEND_URL}/api/annotations" \
 -H "Content-Type: application/json" \
 -d '{
 "text": "Релиз <b>payment_bank</b> v2.4.1 · commit a1b2c3d · <a href=\"https://ci/build/987\">сборка #987</a>",
 "tags": ["release", "env:production"],
 "type": "RELEASE",
 "service": "payment_bank"
 }'

Глобальный релиз (виден на всех дашбордах — service не указан):

curl -X POST "https://${PROTO_BACKEND_URL}/api/annotations" \
 -H "Content-Type: application/json" \
 -d '{"text": "Платформенный релиз v2.4.1", "tags": ["release"], "type": "RELEASE"}'

Окно технических работ (интервальный маркер — заданы time и timeEnd):

curl -X POST "https://${PROTO_BACKEND_URL}/api/annotations" \
 -H "Content-Type: application/json" \
 -d '{
 "text": "Плановое обслуживание БД",
 "tags": ["change", "maintenance"],
 "time": 1730000000000,
 "timeEnd": 1730003600000
 }'

Получить релизы сервиса за период:

curl "https://${PROTO_BACKEND_URL}/api/annotations?from=1729000000000&to=1731000000000&tags=release&service=payment_bank"

Справочник API

Базовый путь — /api/annotations. Время передаётся в миллисекундах эпохи.

Эндпоинты

Метод	Путь	Назначение
`POST`	`/api/annotations`	Создать маркер
`GET`	`/api/annotations`	Получить список маркеров
`PUT`	`/api/annotations/{id}`	Полностью заменить маркер
`PATCH`	`/api/annotations/{id}`	Частично обновить маркер
`DELETE`	`/api/annotations/{id}`	Удалить маркер

Поля запроса (`POST` / `PUT`)

Поле	Обяз.	Тип	Описание
`text`	да	строка	Описание события (допустима HTML-разметка)
`tags`	нет	массив строк	Метки для фильтрации
`time`	нет	число	Время начала, epoch ms (по умолчанию — текущее)
`timeEnd`	нет	число	Время окончания, epoch ms; задаёт интервальный маркер
`service`	нет	строка	Имя сервиса; пусто — глобальное событие
`type`	нет	строка	Тип маркера, например `RELEASE`

Поля идентификаторов дашбордов и панелей Grafana (dashboardUID, panelId) принимаются, но игнорируются: в Proto Observability Platform маркеры привязываются к сервису, а не к конкретному дашборду.

Получение и фильтрация (`GET`)

Параметр	Описание
`from`, `to`	Диапазон по времени, epoch ms
`tags`	Фильтр по тегам (можно повторять). По умолчанию — совпадение по всем; `matchAny=true` — по любому
`type`	Фильтр по типу маркера
`service`	Сервис; возвращаются как его события, так и глобальные
`limit`	Максимум записей (по умолчанию 100)

Совместимость с Grafana

API повторяет контракт Grafana Annotations API: поля text / tags / time / timeEnd, ответы вида {"id", "message"}, возврат списка простым JSON-массивом. Это позволяет переиспользовать привычные инструменты и скрипты записи маркеров. Дополнительно поддержаны расширения Proto — поля service и type.

Хранение и доступ

Срок хранения по умолчанию — 370 дней, настраивается переменной окружения POBP_DATA_RETENTION_ANNOTATIONS_DAYS.
Доступ. Эндпоинт не требует аутентификации и рассчитан на вызов из доверенного сетевого контура (CI/CD-пайплайн, внутренние скрипты). Ограничьте к нему доступ средствами сети.

См. также: Интеграция с CI/CD и Кастомные дашборды.

Документация Proto Observability Platform – annotations