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

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

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

Что это такое

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

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

Метрики показывают, что произошло (выросло время отклика, пошли ошибки), но не отвечают, почему именно в этот момент. Маркеры добавляют недостающий слой контекста: «время отклика подскочило сразу после релиза 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).

Дополнительно маркеры дают контекст дежурному без «археологии» (не нужно искать по 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 / PUT)

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

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

Совместимость с 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 и Кастомные дашборды.