Справочник API платформы

Справочник по API-интерфейсам Proto Observability Platform: описание, протоколы, функциональность.

API для работы с данными телеметрии

Получение (выгрузка) данных

Метрики

Prometheus-совместимый HTTP API для запросов метрик на языке PromQL.

Базовый путь: /promqlapi/

Эндпоинт	Метод	Описание
`/promqlapi/api/v1/query`	GET/POST	Мгновенный запрос (instant query)
`/promqlapi/api/v1/query_range`	GET/POST	Запрос за диапазон времени (range query)
`/promqlapi/api/v1/series`	GET	Метаданные серий
`/promqlapi/api/v1/labels`	GET	Список имён меток
`/promqlapi/api/v1/label/{name}/values`	GET	Значения конкретной метки
`/promqlapi/federate`	GET	Федерация метрик

Протокол: PromQL over HTTP (Prometheus-совместимый API).

Логи

API для запросов логов на языке LogsQL.

Базовый путь: /logsqlapi/

Эндпоинт	Метод	Описание
`/logsqlapi/select/logsql/query`	GET	Запросы логов с синтаксисом LogsQL
`/logsqlapi/select/logsql/hits`	GET	Гистограмма совпадений по времени
`/logsqlapi/select/logsql/field_names`	GET	Доступные имена полей
`/logsqlapi/select/logsql/field_values`	GET	Значения указанного поля

Протокол: LogsQL over HTTP.

Трейсы

Префикс	Описание
`/traces`	Список трейсов, сервисы, операции, инстансы, теги

Метрики сервисов, алерты и аналитика

Аналитические запросы по трейсам, ошибкам, алертам, бизнес-транзакциям и другим доменам выполняются через OLAP API семантического слоя данных.

Базовый путь: /cubejs-api/

Эндпоинт	Метод	Описание
`/cubejs-api/v1/load`	GET/POST	Выполнение OLAP-запросов (меры, измерения, фильтры, время)
`/cubejs-api/v1/meta`	GET	Метаданные схемы (доступные модели, меры, измерения)
`/cubejs-api/v1/sql`	GET/POST	Предпросмотр SQL-запроса

Модели данных: 60+ моделей, покрывающих домены – сервисы, спаны, вызовы, ошибки, RUM, браузер, сессии, бизнес-транзакции, бизнес-процессы, алерты, действия, события, ресурсы, здоровье, воронки, метрики мониторинга БД и другие.

Протокол: OLAP REST API с JSON-языком запросов.

Загрузка внешних данных в платформу

Метрики

Эндпоинт	Метод	Описание
`/promqlapi/api/v1/write`	POST	Remote write (протокол Prometheus remote write)

Протокол: Prometheus remote write.

Логи

Эндпоинт	Метод	Описание
`/insert/opentelemetry/v1/logs`	POST	Приём логов по протоколу OTLP/HTTP (рекомендуется)
`/insert/elasticsearch/_bulk`	POST	Приём логов в формате Elasticsearch Bulk API
`/insert/jsonline`	POST	Приём логов в формате JSON stream (ndjson)
`/insert/loki/api/v1/push`	POST	Приём логов в формате Loki JSON API
`/insert/datadog/api/v2/logs`	POST	Приём логов в формате DataDog API

Параметры обработки полей можно передавать через строку запроса или HTTP-заголовки:

Параметр	HTTP-заголовок	Описание
`_msg_field`	`VL-Msg-Field`	Поле с текстом сообщения (по умолчанию `_msg`)
`_time_field`	`VL-Time-Field`	Поле с временной меткой (по умолчанию `_time`)
`_stream_fields`	`VL-Stream-Fields`	Поля, определяющие лог-поток (через запятую)
`ignore_fields`	`VL-Ignore-Fields`	Поля для исключения (через запятую, поддерживает `prefix*`)
`extra_fields`	`VL-Extra-Fields`	Дополнительные поля в формате `name=value` (через запятую)

Подробнее о настройке агентов и коллекторов: Получение данных логов.

Трейсы

Загрузка трейсов выполняется через инструментацию приложений с помощью трейсеров или OpenTelemetry Collector. Подробнее: Инструментация.

Алерты

Платформа принимает алерты от внешних систем мониторинга в двух форматах:

Эндпоинт	Метод	Формат	Описание
`/api/v2/alertprocess`	POST	Alertmanager webhook	Приём алертов в формате Alertmanager webhook (обёртка с полями `receiver`, `groupKey`, `alerts[]`, `groupLabels`)
`/api/v2/alerts`	POST	Массив алертов	Приём алертов в виде плоского массива объектов, например, от VictoriaMetrics vmalert (поля: `startsAt`, `endsAt`, `generatorURL`, `labels`, `annotations`)

API для управления платформой

Платформа предоставляет REST API для управления конфигурацией. Протокол: REST/JSON.

Правила алертинга

REST API с документацией OpenAPI/Swagger.

Эндпоинт	Метод	Описание
`/rulesapi/rules`	GET/POST/PUT/DELETE	CRUD правил алертинга + клонирование
`/rulesapi/groups`	GET	Список групп правил
`/rulesapi/deploy`	POST	Экспорт и применение конфигурации (YAML)
`/rulesapi/rulepolicy/receivers`	GET/POST/PUT/DELETE	CRUD получателей уведомлений
`/rulesapi/rulepolicy/routes`	GET/POST/PUT/DELETE	CRUD маршрутов + управление приоритетами
`/rulesapi/rulepolicy/deploy`	POST	Применение политики алертинга
`/rulesapi/swagger/*`	GET	OpenAPI/Swagger документация

Бизнес-транзакции

Группа API	Префикс	Описание
Ключевые бизнес-транзакции	`/transactions`	CRUD + массовое удаление
Правила обнаружения BT	`/bt-detection-rules`	CRUD + тестирование паттернов + применение ко всем
RUM бизнес-транзакции	`/rum-key-business-transactions`	CRUD
RUM правила обнаружения	`/rum-bt-detection-rules`	CRUD + тестирование паттернов

Бизнес-процессы

Префикс	Описание
`/business-processes`	CRUD + вложенные шаги + порядок

Сегменты и пороги

Префикс	Описание
`/protoobp-api/segments`	CRUD сегментов + массовое удаление
`/protoobp-api/apdex-thresholds`	CRUD порогов Apdex по сервису
`/protoobp-api/data-extraction-rules`	CRUD правил извлечения данных

Ресурсная модель

Префикс	Описание
`/protoobp-api/resource-types`	CRUD типов ресурсов
`/protoobp-api/resources`	CRUD ресурсов + сводки + соседи + граф зависимостей
`/protoobp-api/resource-relationships`	CRUD связей ресурсов
`/protoobp-api/relationship-types`	CRUD типов связей
`/protoobp-api/ci-classes`	CRUD CI-классов
`/protoobp-api/ci-subclasses`	CRUD CI-подклассов

RBAC-администрирование

Префикс	Описание
`/protoobp-api/rbac/*`	Роли, разрешения, привязки, аудит

Сводная таблица стандартов API

Стандарт	Где используется
PromQL over HTTP	Запросы и запись метрик
LogsQL over HTTP	Запросы логов
OLAP REST API	Аналитические запросы (трейсы, алерты, бизнес-транзакции и др.)
REST/JSON	Управление конфигурацией платформы
REST/HTTP (мультиформатный)	Приём логов (OTLP, Elasticsearch, JSON, Loki, DataDog)
OpenAPI/Swagger	Документация API правил алертинга
Alertmanager webhook	Приём алертов от внешних систем

Аутентификация запросов к OLAP API

Начиная с версии v200 платформа включает RBAC по умолчанию. Все запросы к /cubejs-api/* обязаны нести валидный Bearer токен, выданный сервисом proto-auth. Запросы без токена возвращают 401 TOKEN_MISSING.

Внешний клиент предъявляет access token proto-auth (RS256) в заголовке Authorization: Bearer <jwt>.

Подключение внешнего клиента

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

Шаг 1. Подготовка пользователя. В платформе создаётся отдельный пользователь под интеграцию. В веб-интерфейсе платформы (Настройки → Роли и доступ) этому аккаунту назначаются роли с правом просмотр на сервисы, к которым нужен доступ. Аккаунту с правом {admin, *, *} доступны все сервисы.

Шаг 2. Получение access token у proto-auth:

ACCESS_TOKEN=$(curl -s -X POST \
  "https://<платформа>/realms/protoobp/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=ui" \
  -d "username=$INTEGRATION_USER" \
  -d "password=$INTEGRATION_PASSWORD" \
  | jq -r '.access_token')

Параметры запроса:

Realm — protoobp (фиксированное имя realm в proto-auth).
client_id=ui — клиент realm-а protoobp с включённым Direct Access Grants. Дополнительный клиент под интеграцию заводить не требуется.
Endpoint — стандартный OpenID Connect token endpoint в proto-auth.

Шаг 3. Вызов CubeJS API через платформу:

curl -s -X POST "https://<платформа>/cubejs-api/v1/load" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "measures": ["Calls.count"],
      "dimensions": ["Calls.service"],
      "timeDimensions": [{"dimension": "Calls.date", "dateRange": "today"}]
    }
  }'

Сервисы, на которые у пользователя нет прав, в результате не появляются.

Типовые ошибки и замечания

Время жизни access token. Токены proto-auth короткоживущие (по умолчанию около 5 минут). Долгоживущие интеграции должны обновлять токен через refresh_token либо повторно вызывать /token перед каждым запросом.
Отдельный аккаунт на интеграцию. Каждой интеграции рекомендуется заводить собственного пользователя платформы с минимально необходимым набором ролей — это упрощает аудит и отзыв прав.
Миграция с pre-v200. Скрипты, работавшие с CubeJS API на версии v199 без аутентификации, на v200 будут получать 401 TOKEN_MISSING. Решение — завести отдельного пользователя платформы, назначить роли и перейти на схему авторизации с Bearer-токеном, описанную выше.