Документация Proto Observability Platform – api /docs/tags/api/ Recent content in api on Документация Proto Observability Platform Hugo -- gohugo.io ru Guides: Справочник API платформы /docs/guides/api_reference/ Mon, 01 Jan 0001 00:00:00 +0000 /docs/guides/api_reference/ <p>На этой странице:</p> <ul> <li><a href="#api-%D0%B4%D0%BB%D1%8F-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%8B-%D1%81-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D0%BC%D0%B8-%D1%82%D0%B5%D0%BB%D0%B5%D0%BC%D0%B5%D1%82%D1%80%D0%B8%D0%B8">API для работы с данными телеметрии</a> <ul> <li><a href="#%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B2%D1%8B%D0%B3%D1%80%D1%83%D0%B7%D0%BA%D0%B0-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85">Получение (выгрузка) данных</a> <ul> <li><a href="#%D0%BC%D0%B5%D1%82%D1%80%D0%B8%D0%BA%D0%B8">Метрики</a></li> <li><a href="#%D0%BB%D0%BE%D0%B3%D0%B8">Логи</a></li> <li><a href="#%D1%82%D1%80%D0%B5%D0%B9%D1%81%D1%8B">Трейсы</a></li> <li><a href="#%D0%BC%D0%B5%D1%82%D1%80%D0%B8%D0%BA%D0%B8-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D0%BE%D0%B2-%D0%B0%D0%BB%D0%B5%D1%80%D1%82%D1%8B-%D0%B8-%D0%B0%D0%BD%D0%B0%D0%BB%D0%B8%D1%82%D0%B8%D0%BA%D0%B0">Метрики сервисов, алерты и аналитика</a></li> </ul> </li> <li><a href="#%D0%B7%D0%B0%D0%B3%D1%80%D1%83%D0%B7%D0%BA%D0%B0-%D0%B2%D0%BD%D0%B5%D1%88%D0%BD%D0%B8%D1%85-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85-%D0%B2-%D0%BF%D0%BB%D0%B0%D1%82%D1%84%D0%BE%D1%80%D0%BC%D1%83">Загрузка внешних данных в платформу</a> <ul> <li><a href="#%D0%BC%D0%B5%D1%82%D1%80%D0%B8%D0%BA%D0%B8-1">Метрики</a></li> <li><a href="#%D0%BB%D0%BE%D0%B3%D0%B8-1">Логи</a></li> <li><a href="#%D1%82%D1%80%D0%B5%D0%B9%D1%81%D1%8B-1">Трейсы</a></li> <li><a href="#%D0%B0%D0%BB%D0%B5%D1%80%D1%82%D1%8B">Алерты</a></li> </ul> </li> </ul> </li> <li><a href="#api-%D0%B4%D0%BB%D1%8F-%D1%83%D0%BF%D1%80%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F-%D0%BF%D0%BB%D0%B0%D1%82%D1%84%D0%BE%D1%80%D0%BC%D0%BE%D0%B9">API для управления платформой</a> <ul> <li><a href="#%D0%BF%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0-%D0%B0%D0%BB%D0%B5%D1%80%D1%82%D0%B8%D0%BD%D0%B3%D0%B0">Правила алертинга</a></li> <li><a href="#%D0%B1%D0%B8%D0%B7%D0%BD%D0%B5%D1%81-%D1%82%D1%80%D0%B0%D0%BD%D0%B7%D0%B0%D0%BA%D1%86%D0%B8%D0%B8">Бизнес-транзакции</a></li> <li><a href="#%D0%B1%D0%B8%D0%B7%D0%BD%D0%B5%D1%81-%D0%BF%D1%80%D0%BE%D1%86%D0%B5%D1%81%D1%81%D1%8B">Бизнес-процессы</a></li> <li><a href="#%D1%81%D0%B5%D0%B3%D0%BC%D0%B5%D0%BD%D1%82%D1%8B-%D0%B8-%D0%BF%D0%BE%D1%80%D0%BE%D0%B3%D0%B8">Сегменты и пороги</a></li> <li><a href="#%D1%80%D0%B5%D1%81%D1%83%D1%80%D1%81%D0%BD%D0%B0%D1%8F-%D0%BC%D0%BE%D0%B4%D0%B5%D0%BB%D1%8C">Ресурсная модель</a></li> <li><a href="#rbac-%D0%B0%D0%B4%D0%BC%D0%B8%D0%BD%D0%B8%D1%81%D1%82%D1%80%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5">RBAC-администрирование</a></li> </ul> </li> <li><a href="#%D1%81%D0%B2%D0%BE%D0%B4%D0%BD%D0%B0%D1%8F-%D1%82%D0%B0%D0%B1%D0%BB%D0%B8%D1%86%D0%B0-%D1%81%D1%82%D0%B0%D0%BD%D0%B4%D0%B0%D1%80%D1%82%D0%BE%D0%B2-api">Сводная таблица стандартов API</a></li> </ul> <p>Proto Observability Platform предоставляет набор API для загрузки и выгрузки данных телеметрии, а также для управления конфигурацией платформы. Все API доступны через единую точку входа платформы.</p> <hr> <h2 id="api-для-работы-с-данными-телеметрии">API для работы с данными телеметрии</h2> <h3 id="получение-выгрузка-данных">Получение (выгрузка) данных</h3> <h4 id="метрики">Метрики</h4> <p>Prometheus-совместимый HTTP API для запросов метрик на языке PromQL.</p> <p><strong>Базовый путь:</strong> <code>/promqlapi/</code></p> <table> <thead> <tr> <th>Эндпоинт</th> <th>Метод</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/promqlapi/api/v1/query</code></td> <td>GET/POST</td> <td>Мгновенный запрос (instant query)</td> </tr> <tr> <td><code>/promqlapi/api/v1/query_range</code></td> <td>GET/POST</td> <td>Запрос за диапазон времени (range query)</td> </tr> <tr> <td><code>/promqlapi/api/v1/series</code></td> <td>GET</td> <td>Метаданные серий</td> </tr> <tr> <td><code>/promqlapi/api/v1/labels</code></td> <td>GET</td> <td>Список имён меток</td> </tr> <tr> <td><code>/promqlapi/api/v1/label/{name}/values</code></td> <td>GET</td> <td>Значения конкретной метки</td> </tr> <tr> <td><code>/promqlapi/federate</code></td> <td>GET</td> <td>Федерация метрик</td> </tr> </tbody> </table> <p><strong>Протокол:</strong> PromQL over HTTP (Prometheus-совместимый API).</p> <h4 id="логи">Логи</h4> <p>API для запросов логов на языке LogsQL.</p> <p><strong>Базовый путь:</strong> <code>/logsqlapi/</code></p> <table> <thead> <tr> <th>Эндпоинт</th> <th>Метод</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/logsqlapi/select/logsql/query</code></td> <td>GET</td> <td>Запросы логов с синтаксисом LogsQL</td> </tr> <tr> <td><code>/logsqlapi/select/logsql/hits</code></td> <td>GET</td> <td>Гистограмма совпадений по времени</td> </tr> <tr> <td><code>/logsqlapi/select/logsql/field_names</code></td> <td>GET</td> <td>Доступные имена полей</td> </tr> <tr> <td><code>/logsqlapi/select/logsql/field_values</code></td> <td>GET</td> <td>Значения указанного поля</td> </tr> </tbody> </table> <p><strong>Протокол:</strong> LogsQL over HTTP.</p> <h4 id="трейсы">Трейсы</h4> <table> <thead> <tr> <th>Префикс</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/traces</code></td> <td>Список трейсов, сервисы, операции, инстансы, теги</td> </tr> </tbody> </table> <h4 id="метрики-сервисов-алерты-и-аналитика">Метрики сервисов, алерты и аналитика</h4> <p>Аналитические запросы по трейсам, ошибкам, алертам, бизнес-транзакциям и другим доменам выполняются через OLAP API семантического слоя данных.</p> <p><strong>Базовый путь:</strong> <code>/cubejs-api/</code></p> <table> <thead> <tr> <th>Эндпоинт</th> <th>Метод</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/cubejs-api/v1/load</code></td> <td>GET/POST</td> <td>Выполнение OLAP-запросов (меры, измерения, фильтры, время)</td> </tr> <tr> <td><code>/cubejs-api/v1/meta</code></td> <td>GET</td> <td>Метаданные схемы (доступные модели, меры, измерения)</td> </tr> <tr> <td><code>/cubejs-api/v1/sql</code></td> <td>GET/POST</td> <td>Предпросмотр SQL-запроса</td> </tr> </tbody> </table> <p><strong>Модели данных:</strong> 60+ моделей, покрывающих домены &ndash; сервисы, спаны, вызовы, ошибки, RUM, браузер, сессии, бизнес-транзакции, бизнес-процессы, алерты, действия, события, ресурсы, здоровье, воронки, метрики мониторинга БД и другие.</p> <p><strong>Протокол:</strong> OLAP REST API с JSON-языком запросов.</p> <hr> <h3 id="загрузка-внешних-данных-в-платформу">Загрузка внешних данных в платформу</h3> <h4 id="метрики-1">Метрики</h4> <table> <thead> <tr> <th>Эндпоинт</th> <th>Метод</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/promqlapi/api/v1/write</code></td> <td>POST</td> <td>Remote write (протокол Prometheus remote write)</td> </tr> </tbody> </table> <p><strong>Протокол:</strong> Prometheus remote write.</p> <h4 id="логи-1">Логи</h4> <table> <thead> <tr> <th>Эндпоинт</th> <th>Метод</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/insert/opentelemetry/v1/logs</code></td> <td>POST</td> <td>Приём логов по протоколу OTLP/HTTP (рекомендуется)</td> </tr> <tr> <td><code>/insert/elasticsearch/_bulk</code></td> <td>POST</td> <td>Приём логов в формате Elasticsearch Bulk API</td> </tr> <tr> <td><code>/insert/jsonline</code></td> <td>POST</td> <td>Приём логов в формате JSON stream (ndjson)</td> </tr> <tr> <td><code>/insert/loki/api/v1/push</code></td> <td>POST</td> <td>Приём логов в формате Loki JSON API</td> </tr> <tr> <td><code>/insert/datadog/api/v2/logs</code></td> <td>POST</td> <td>Приём логов в формате DataDog API</td> </tr> </tbody> </table> <p>Параметры обработки полей можно передавать через строку запроса или HTTP-заголовки:</p> <table> <thead> <tr> <th>Параметр</th> <th>HTTP-заголовок</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>_msg_field</code></td> <td><code>VL-Msg-Field</code></td> <td>Поле с текстом сообщения (по умолчанию <code>_msg</code>)</td> </tr> <tr> <td><code>_time_field</code></td> <td><code>VL-Time-Field</code></td> <td>Поле с временной меткой (по умолчанию <code>_time</code>)</td> </tr> <tr> <td><code>_stream_fields</code></td> <td><code>VL-Stream-Fields</code></td> <td>Поля, определяющие лог-поток (через запятую)</td> </tr> <tr> <td><code>ignore_fields</code></td> <td><code>VL-Ignore-Fields</code></td> <td>Поля для исключения (через запятую, поддерживает <code>prefix*</code>)</td> </tr> <tr> <td><code>extra_fields</code></td> <td><code>VL-Extra-Fields</code></td> <td>Дополнительные поля в формате <code>name=value</code> (через запятую)</td> </tr> </tbody> </table> <p>Подробнее о настройке агентов и коллекторов: <a href="../../instrumentation/logs/data-ingestion/">Получение данных логов</a>.</p> <h4 id="трейсы-1">Трейсы</h4> <p>Загрузка трейсов выполняется через инструментацию приложений с помощью трейсеров или OpenTelemetry Collector. Подробнее: <a href="../../instrumentation/tracing/">Инструментация</a>.</p> <h4 id="алерты">Алерты</h4> <p>Платформа принимает алерты от внешних систем мониторинга в двух форматах:</p> <table> <thead> <tr> <th>Эндпоинт</th> <th>Метод</th> <th>Формат</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/api/v2/alertprocess</code></td> <td>POST</td> <td>Alertmanager webhook</td> <td>Приём алертов в формате Alertmanager webhook (обёртка с полями <code>receiver</code>, <code>groupKey</code>, <code>alerts[]</code>, <code>groupLabels</code>)</td> </tr> <tr> <td><code>/api/v2/alerts</code></td> <td>POST</td> <td>Массив алертов</td> <td>Приём алертов в виде плоского массива объектов, например, от VictoriaMetrics vmalert (поля: <code>startsAt</code>, <code>endsAt</code>, <code>generatorURL</code>, <code>labels</code>, <code>annotations</code>)</td> </tr> </tbody> </table> <hr> <h2 id="api-для-управления-платформой">API для управления платформой</h2> <p>Платформа предоставляет REST API для управления конфигурацией. <strong>Протокол:</strong> REST/JSON.</p> <h4 id="правила-алертинга">Правила алертинга</h4> <p>REST API с документацией OpenAPI/Swagger.</p> <table> <thead> <tr> <th>Эндпоинт</th> <th>Метод</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/rulesapi/rules</code></td> <td>GET/POST/PUT/DELETE</td> <td>CRUD правил алертинга + клонирование</td> </tr> <tr> <td><code>/rulesapi/groups</code></td> <td>GET</td> <td>Список групп правил</td> </tr> <tr> <td><code>/rulesapi/deploy</code></td> <td>POST</td> <td>Экспорт и применение конфигурации (YAML)</td> </tr> <tr> <td><code>/rulesapi/rulepolicy/receivers</code></td> <td>GET/POST/PUT/DELETE</td> <td>CRUD получателей уведомлений</td> </tr> <tr> <td><code>/rulesapi/rulepolicy/routes</code></td> <td>GET/POST/PUT/DELETE</td> <td>CRUD маршрутов + управление приоритетами</td> </tr> <tr> <td><code>/rulesapi/rulepolicy/deploy</code></td> <td>POST</td> <td>Применение политики алертинга</td> </tr> <tr> <td><code>/rulesapi/swagger/*</code></td> <td>GET</td> <td>OpenAPI/Swagger документация</td> </tr> </tbody> </table> <h4 id="бизнес-транзакции">Бизнес-транзакции</h4> <table> <thead> <tr> <th>Группа API</th> <th>Префикс</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td>Ключевые бизнес-транзакции</td> <td><code>/transactions</code></td> <td>CRUD + массовое удаление</td> </tr> <tr> <td>Правила обнаружения BT</td> <td><code>/bt-detection-rules</code></td> <td>CRUD + тестирование паттернов + применение ко всем</td> </tr> <tr> <td>RUM бизнес-транзакции</td> <td><code>/rum-key-business-transactions</code></td> <td>CRUD</td> </tr> <tr> <td>RUM правила обнаружения</td> <td><code>/rum-bt-detection-rules</code></td> <td>CRUD + тестирование паттернов</td> </tr> </tbody> </table> <h4 id="бизнес-процессы">Бизнес-процессы</h4> <table> <thead> <tr> <th>Префикс</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/business-processes</code></td> <td>CRUD + вложенные шаги + порядок</td> </tr> </tbody> </table> <h4 id="сегменты-и-пороги">Сегменты и пороги</h4> <table> <thead> <tr> <th>Префикс</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/protoobp-api/segments</code></td> <td>CRUD сегментов + массовое удаление</td> </tr> <tr> <td><code>/protoobp-api/apdex-thresholds</code></td> <td>CRUD порогов Apdex по сервису</td> </tr> <tr> <td><code>/protoobp-api/data-extraction-rules</code></td> <td>CRUD правил извлечения данных</td> </tr> </tbody> </table> <h4 id="ресурсная-модель">Ресурсная модель</h4> <table> <thead> <tr> <th>Префикс</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/protoobp-api/resource-types</code></td> <td>CRUD типов ресурсов</td> </tr> <tr> <td><code>/protoobp-api/resources</code></td> <td>CRUD ресурсов + сводки + соседи + граф зависимостей</td> </tr> <tr> <td><code>/protoobp-api/resource-relationships</code></td> <td>CRUD связей ресурсов</td> </tr> <tr> <td><code>/protoobp-api/relationship-types</code></td> <td>CRUD типов связей</td> </tr> <tr> <td><code>/protoobp-api/ci-classes</code></td> <td>CRUD CI-классов</td> </tr> <tr> <td><code>/protoobp-api/ci-subclasses</code></td> <td>CRUD CI-подклассов</td> </tr> </tbody> </table> <h4 id="rbac-администрирование">RBAC-администрирование</h4> <table> <thead> <tr> <th>Префикс</th> <th>Описание</th> </tr> </thead> <tbody> <tr> <td><code>/protoobp-api/rbac/*</code></td> <td>Роли, разрешения, привязки, аудит</td> </tr> </tbody> </table> <hr> <h2 id="сводная-таблица-стандартов-api">Сводная таблица стандартов API</h2> <table> <thead> <tr> <th>Стандарт</th> <th>Где используется</th> </tr> </thead> <tbody> <tr> <td>PromQL over HTTP</td> <td>Запросы и запись метрик</td> </tr> <tr> <td>LogsQL over HTTP</td> <td>Запросы логов</td> </tr> <tr> <td>OLAP REST API</td> <td>Аналитические запросы (трейсы, алерты, бизнес-транзакции и др.)</td> </tr> <tr> <td>REST/JSON</td> <td>Управление конфигурацией платформы</td> </tr> <tr> <td>REST/HTTP (мультиформатный)</td> <td>Приём логов (OTLP, Elasticsearch, JSON, Loki, DataDog)</td> </tr> <tr> <td>OpenAPI/Swagger</td> <td>Документация API правил алертинга</td> </tr> <tr> <td>Alertmanager webhook</td> <td>Приём алертов от внешних систем</td> </tr> </tbody> </table>