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

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

• API для работы с данными телеметрии
  • Получение (выгрузка) данных
    • Метрики
    • Логи
    • Трейсы
      • Экспорт отдельного трейса в открытых форматах
    • Метрики сервисов, алерты и аналитика
  • Загрузка внешних данных в платформу
    • Метрики
    • Логи
    • Трейсы
    • Алерты
• API для управления платформой
  • Правила алертинга
  • Бизнес-транзакции
  • Бизнес-процессы
  • Сегменты и пороги
  • Ресурсная модель
  • RBAC-администрирование
• Сводная таблица стандартов API
• Аутентификация запросов к OLAP API
  • Подключение внешнего клиента
  • Типовые ошибки и замечания

Proto Observability Platform предоставляет набор API для загрузки и выгрузки данных телеметрии, а также для управления конфигурацией платформы. Все API доступны через единую точку входа платформы.

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

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

Метрики

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

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

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

Логи

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

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

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

Трейсы

Экспорт отдельного трейса в открытых форматах

Любой отдельный распределённый трейс можно выгрузить в открытом, вендоронезависимом формате — для независимого анализа, отладки, долговременного архива проблемных трейсов или передачи в другую команду. Данные платформы не заперты в проприетарном формате и в любой момент могут быть выгружены в переносимом виде. Выгрузка доступна двумя путями: по API (описан ниже) и из интерфейса платформы — см. Выгрузка из интерфейса. Поддерживаются три формата:

Все три эндпоинта авторизуются тем же токеном, что и остальные API платформы, и подчиняются тем же правам доступа к сервисам (RBAC), что и просмотр трейса в интерфейсе.

Параметры запроса (общие для всех форматов):

Коды ответа (общие для всех форматов):

• 200 — трейс успешно выгружен;
• 400 — идентификатор трейса не передан или имеет некорректный формат;
• 403 — у пользователя нет доступа ни к одному сервису, участвующему в трейсе;
• 404 — трейс не найден (не существует или вышел за пределы срока хранения).

Пример запроса (замените otlp на zipkin или jaeger для соответствующего формата):

curl -H "Authorization: Bearer $TOKEN" \
  "https://<адрес-платформы>/protoobp-api/traces/<traceId>/otlp" -o trace-otlp.json

Выгрузка из интерфейса

Те же форматы доступны без обращения к API. Откройте трейс (раздел Трейсы или переход из дашборда сервиса, транзакции либо алерта) и на вкладке Дерево нажмите кнопку Экспорт в панели инструментов водопада. В меню четыре пункта:

Файл сохраняется браузером как обычная загрузка. Окно поиска спанов совпадает с временным диапазоном, выбранным в панели времени, — тем же, в котором открыт водопад трейса. Права доступа те же, что и при просмотре трейса: если у учётной записи нет доступа к сервисам трейса, интерфейс сообщит о нехватке прав, а если трейс уже вышел за пределы срока хранения — что трейс не найден.

Формат OTLP/JSON

Ответ соответствует конвенциям OTLP/JSON: идентификаторы трейса и спанов — шестнадцатеричные строки, метки времени в наносекундах — строки, перечислимые поля (kind, status.code) — числа. Спаны сгруппированы по сервису: на каждый сервис — один блок resourceSpans с атрибутом ресурса service.name. Тело ответа — ExportTraceServiceRequest в кодировке OTLP/JSON, поэтому его можно без преобразований загрузить в любой инструмент, поддерживающий приём OTLP-данных.

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "payment" } }
        ]
      },
      "scopeSpans": [
        {
          "scope": { "name": "protoobp" },
          "spans": [
            {
              "traceId": "abcdef0123456789abcdef0123456789",
              "spanId": "0000000000000002",
              "parentSpanId": "0000000000000001",
              "name": "POST /pay",
              "kind": 3,
              "startTimeUnixNano": "1737800000000000000",
              "endTimeUnixNano": "1737800000200000000",
              "attributes": [
                { "key": "http.method", "value": { "stringValue": "POST" } }
              ],
              "status": { "code": 2, "message": "gateway timeout" }
            }
          ]
        }
      ]
    }
  ]
}

Атрибуты спана формируются из его тегов и числовых метрик; корневой спан не содержит поля parentSpanId, а поле status присутствует только у спанов с ошибкой (code: 2).

Формат Zipkin v2 JSON

Ответ — это голый JSON-массив объектов-спанов по спецификации Zipkin v2. Идентификаторы трейса и спанов — шестнадцатеричные строки в нижнем регистре (traceId — 32 символа, id и parentId — 16). Метки времени timestamp и duration — в микросекундах. Вид спана kind (SERVER/CLIENT/PRODUCER/CONSUMER) заполняется, если известен; сервис-источник указывается в localEndpoint.serviceName, удалённый сервис (для исходящих вызовов) — в remoteEndpoint.serviceName.

[
  {
    "traceId": "abcdef0123456789abcdef0123456789",
    "id": "0000000000000002",
    "parentId": "0000000000000001",
    "name": "POST /pay",
    "kind": "CLIENT",
    "timestamp": 1737800000000000,
    "duration": 200000,
    "localEndpoint": { "serviceName": "payment" },
    "remoteEndpoint": { "serviceName": "payment-gateway" },
    "tags": {
      "http.method": "POST",
      "http.status_code": "504",
      "error": "true"
    }
  }
]

Теги спана формируются из его строковых тегов и числовых метрик; корневой спан не содержит поля parentId, а тег error со значением true присутствует только у спанов с ошибкой. Выгруженный массив можно без преобразований загрузить прямо в приёмник Zipkin:

curl -X POST -H "Content-Type: application/json" \
  --data @trace-zipkin.json \
  "http://<адрес-zipkin>:9411/api/v2/spans"

Формат Jaeger JSON

Ответ — объект-обёртка в нативной модели Jaeger, том же представлении, которое отдаёт jaeger-query по GET /api/traces/{id} (поле data). Полученный файл можно открыть прямо в Jaeger UI: на странице поиска трейсов нажмите «Upload JSON» / «Load JSON» и выберите файл — трейс отобразится со всей иерархией спанов.

{
  "data": [
    {
      "traceID": "00000000000000000000000000000001",
      "spans": [
        {
          "traceID": "00000000000000000000000000000001",
          "spanID": "0000000000000002",
          "operationName": "POST /pay",
          "references": [
            { "refType": "CHILD_OF", "traceID": "00000000000000000000000000000001", "spanID": "0000000000000001" }
          ],
          "startTime": 5000500,
          "duration": 200000,
          "tags": [
            { "key": "span.kind", "type": "string", "value": "client" },
            { "key": "error", "type": "bool", "value": true }
          ],
          "logs": [],
          "processID": "p2",
          "warnings": null
        }
      ],
      "processes": {
        "p1": { "serviceName": "cart", "tags": [] },
        "p2": { "serviceName": "payment", "tags": [] }
      },
      "warnings": null
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "errors": null
}

Ключевые особенности представления:

• Идентификаторы — шестнадцатеричные строки в нижнем регистре: traceID — 32 символа, spanID и spanID в ссылках — 16.
• Метки времени startTime и duration — в микросекундах.
• Родственные связи выражаются через массив references (тип CHILD_OF); корневой спан имеет пустой массив references.
• Теги типизированы ({key, type, value}): строковые теги спана — string, числовые метрики — float64, признак ошибки — error: true (bool, присутствует только у спанов с ошибкой). Вид спана span.kind попадает в теги из метаданных спана.
• Каждый спан ссылается на процесс (processID); таблица processes сопоставляет идентификатор процесса сервису-источнику (serviceName).

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

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

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

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

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

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

Метрики

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

Логи

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

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

Трейсы

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

Алерты

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

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

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

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

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

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

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

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

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

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

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

Аутентификация запросов к 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-токеном, описанную выше.