Guides: Приём ошибок из Sentry SDK

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

Доступно начиная с версии 202.

Proto Observability Platform принимает ошибки напрямую из приложений, инструментированных открытыми Sentry SDK (Python, JavaScript/Node.js, Java, Go, PHP, Ruby, .NET и другие). Чтобы начать отправлять ошибки в платформу, достаточно указать в SDK адрес платформы (DSN) — переписывать код приложения или менять библиотеку не нужно.

Это удобный способ быстро начать работу с платформой: если в приложениях уже используется Sentry SDK, вы получаете анализ ошибок в ProtoOBP «в день один», а позже можете подключить полноценный трейсер и собирать не только ошибки, но и трейсы, транзакции и метрики.

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

Как это работает
Шаг 1. Настройка DSN
Шаг 2. Сопоставление с сервисом
Примеры отправки
Что вы увидите в платформе
Дополнительные настройки
Ограничения и следующий шаг

Как это работает

Платформа предоставляет приёмный интерфейс, совместимый с протоколом Sentry. Sentry SDK отправляет событие об ошибке на адрес из DSN, платформа принимает его, нормализует и сохраняет как ошибку сервиса. Далее ошибка попадает в стандартный модуль Анализ ошибок APM: события объединяются в группы, для каждой группы доступны стек-трейс, сообщения, счётчики и динамика во времени.

Отдельная настройка модуля не требуется — ошибки из Sentry SDK отображаются в тех же разделах, что и ошибки, собранные трейсерами платформы.

Шаг 1. Настройка DSN

В Sentry SDK адрес приёма задаётся строкой DSN вида:

http://<public_key>@<адрес_платформы>/<project_id>

<public_key> — произвольный идентификатор проекта; используется для сопоставления с сервисом (см. шаг 2).
<адрес_платформы> — адрес приёма телеметрии Proto Observability Platform (тот же хост, на который отправляют данные агенты и трейсеры платформы). Для внешних приложений используйте https:// и публичный адрес платформы.
<project_id> — любое целое число.

SDK самостоятельно формирует из DSN путь приёма /api/<project_id>/envelope/ (поддерживается и устаревший путь /api/<project_id>/store/), поэтому в самом приложении достаточно указать только DSN.

Шаг 2. Сопоставление с сервисом

Ошибки в платформе группируются по сервису. Имя сервиса для входящих Sentry-ошибок определяется в следующем порядке:

Явное сопоставление по public_key из DSN — переменная окружения POBP_TRACE_PROCESSOR_SENTRY_PROJECT_MAP (JSON-объект ключ → имя сервиса), задаётся для сервиса proto-trace-processor:
```
POBP_TRACE_PROCESSOR_SENTRY_PROJECT_MAP={"checkout-key":"checkout-service","billing-key":"billing"}
```
Если ключ не задан в сопоставлении — используется тег service из события.
Если тег не задан — имя хоста (server_name) из события.

Рекомендуем выделять по одному DSN (public_key) на сервис — это соответствует модели проектов Sentry и даёт корректную группировку ошибок по сервисам.

Примеры отправки

Python:

import sentry_sdk

sentry_sdk.init(
 dsn="https://checkout-key@demo.proto.group/1",
 environment="production",
 release="checkout@1.4.2",
)
sentry_sdk.set_tag("service", "checkout-service")

try:
 1 / 0
except Exception:
 sentry_sdk.capture_exception()

JavaScript (браузер / Node.js):

import * as Sentry from "@sentry/browser";

Sentry.init({
 dsn: "https://frontend-key@demo.proto.group/2",
 environment: "production",
 release: "web@2.0.0",
});

Что вы увидите в платформе

Ошибки, отправленные через Sentry SDK, отображаются в модуле APM в разделе Ошибки, а также на вкладке Ошибки соответствующего сервиса. Для каждой группы ошибок доступны:

тип и сообщение ошибки, стек-трейс;
количество событий, первое и последнее появление, динамика во времени;
окружение (environment) и версия приложения (release).

Группа определяется по типу ошибки и месту её возникновения в коде (верхний кадр стека приложения), а при заданном в SDK «отпечатке» (fingerprint) — по нему.

Дополнительные настройки

Все переменные окружения задаются для сервиса proto-trace-processor и имеют рабочие значения по умолчанию.

Переменная	По умолчанию	Назначение
`POBP_TRACE_PROCESSOR_SENTRY_PROJECT_MAP`	`{}`	Сопоставление `public_key`/`project_id` → имя сервиса.
`POBP_TRACE_PROCESSOR_SENTRY_MIN_LEVEL`	`error`	Минимальный уровень принимаемых событий (`debug`/`info`/`warning`/`error`/`fatal`).
`POBP_TRACE_PROCESSOR_SENTRY_MAX_EPS`	`100`	Ограничение числа событий в секунду на проект (защита от всплесков).
`POBP_TRACE_PROCESSOR_SENTRY_MAX_BODY_BYTES`	`16777216`	Максимальный размер запроса (16 МБ).
`POBP_TRACE_PROCESSOR_SENTRY_MAX_DECOMPRESSED_BYTES`	`67108864`	Максимальный размер после распаковки (64 МБ).

Ограничения и следующий шаг

Sentry-события содержат отдельные ошибки, но не распределённые трейсы. Поэтому приложение, отправляющее в платформу только ошибки через Sentry SDK, отображается в разделе Ошибки, но не появляется как полноценный сервис APM (с трейсами, транзакциями и метриками производительности).

Чтобы получить полную наблюдаемость, подключите к этому же приложению полноценный трейсер Proto Observability Platform или OpenTelemetry, указав то же имя сервиса. Ошибки из Sentry SDK и данные трейсера объединятся по имени сервиса, и приложение станет полноценным сервисом APM с трейсами, транзакциями, метриками и ошибками в едином интерфейсе.

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