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

Alerting: Метрики и выражения для правил алертинга

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

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

Языки выражений
Доступные метрики сервисов
Лейблы метрик
Синтаксис фильтрации и примеры выражений
Где посмотреть список метрик
Аннотации со ссылками на дашборды

Эта страница — справочник для составления выражений в правилах алертинга. О том, как создавать правила в веб-интерфейсе (поля формы, предпросмотр, работа с правилами), см. Настройка оповещений. Обзор модуля алертинга — на странице Алертинг в Proto Observability Platform.

Языки выражений

Proto Observability Platform поддерживает выражения в правилах алертинга, написанные на языках PromQL и MetricsQL.

Правило срабатывает, когда выражение возвращает результат. Например, выражение ... > 100 вернёт серии только для тех сущностей, у которых значение превышает порог 100, — именно по ним и сработает алерт.

Доступные метрики сервисов

Ниже перечислены ключевые метрики сервисов, доступные для правил алертинга. Список не исчерпывающий: в правилах можно использовать любую метрику из хранилища метрик (инфраструктурные, Kubernetes, метрики БД и др.) — полный каталог доступен в Браузере метрик. Кроме того, набор метрик, для которых строится базовая линия, можно расширить через конфигурацию (см. Выявление аномалий → Как добавить метрики).

Ключевые метрики сервисов:

services_calls: количество вызовов сервиса за интервал;
services_callduration: среднее время отклика сервиса, в миллисекундах;
services_errorcallsperc: доля вызовов с ошибками, в процентах (от 0 до 100);
services_apdex: значение APDEX сервиса, от 0 до 1 (1 — все запросы обслужены в пределах целевого времени).

Для трёх из этих метрик платформа дополнительно строит ML-базовую линию (прогноз) — метрики с суффиксом _prophet: services_calls_prophet, services_callduration_prophet, services_errorcallsperc_prophet. Значения прогноза различаются по лейблу value_type (например, yhat_upper — верхняя граница нормы). Эти метрики используются встроенными правилами выявления аномалий — см. Выявление аномалий.

Метрики для дашбордов

Перечисленные метрики предназначены для алертинга. Полный список метрик, доступных для визуализации на OLAP-дашбордах, можно посмотреть при создании дашборда в режиме «OLAP Мастер» — см. руководство Кастомные дашборды.

Лейблы метрик

Для сервисов доступны следующие лейблы метрик:

service: имя сервиса, аналогичное отображаемому имени сервиса в разделе Приложения > Сервисы;
service_id: внутренний идентификатор сервиса для генерации ссылки на дашборд (см. Аннотации со ссылками на дашборды);
host, service_id_host: хост и его идентификатор, на котором наблюдается сервис (используются в ссылках на дашборды сервера и контейнера).

Синтаксис фильтрации и примеры выражений

Для применения в правилах фильтра по конкретному сервису используйте синтаксис метрика{лейбл="значение"}.

Например, выражение services_callduration{service="credit-bureau-service"} вернёт среднее время отклика сервиса credit-bureau-service в миллисекундах.

Пример выражения для правила (время отклика сервиса больше 100 мс):

avg(services_callduration{service="credit-bureau-service"}) by (service, service_id) > 100

Разбор выражения:

services_callduration — метрика: время отклика сервиса (в миллисекундах);
{service="credit-bureau-service"} — фильтр по имени сервиса;
avg(...) by (service, service_id) > 100 — агрегация по лейблам service и service_id (лейбл service_id нужен, чтобы в аннотациях получить ссылку на дашборд сервиса).

Где посмотреть список метрик

Полный список доступных метрик с поиском доступен в Браузере метрик (Metric Explorer): откройте раздел Метрики > Браузер в главном меню. Введите часть имени метрики в поле поиска — например, services покажет все метрики сервисов.

Скриншот: Браузер метрик — поиск по каталогу метрик (запрос services).

Браузер метрик также позволяет изучать лейблы метрик, количество временных рядов и строить запросы визуально. Подробнее — в руководстве Браузер метрик и построитель PromQL-запросов.

Аннотации со ссылками на дашборды

Аннотации и лейблы задаются в правиле алертинга (см. Настройка оповещений → Лейблы и аннотации):

аннотации позволяют добавлять дополнительные метки к алертам; аннотации приходят в уведомления (Email, Telegram, Webhook и т. д.);
лейблы позволяют группировать алерты и используются в политиках маршрутизации алертов.

Зарезервированные ключи (имена) аннотаций формируют кликабельные ссылки на дашборды Proto OBP:

dashboard, dashboardService — ссылка на дашборд сервиса. Используйте следующее значение:

{{ $externalURL }}/dashboard/GENERAL/Service/{{ .Labels.service_id | reReplaceAll "__" "==" | reReplaceAll "_" "=" }}/Proto-General-Service

dashboardHost — ссылка на дашборд сервера. Используйте следующее значение:
```
{{ $externalURL }}/dashboard/OS_LINUX/Service/{{ .Labels.service_id_host }}/Proto-Linux-Service
```

dashboardContainer — ссылка на дашборд контейнера. Используйте следующее значение:

{{ $externalURL }}/dashboard/OS_LINUX/Endpoint/{{ .Labels.service_id_host }}/{{ .Labels.service_id_host }}_{{ .Labels.service_id_container }}/Proto-Linux-Docker

Примеры использования аннотаций — ссылок на дашборды:

Telegram-уведомления:
Веб-интерфейс Proto OBP:

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