Как перейти с Sentry на self-hosted Gotcha

2026-07-22 · Автор OtezVikentiy

Gotcha принимает события и транзакции по протоколу приёма Sentry, поэтому переход с Sentry на self-hosted Gotcha сводится к одному действию: поднять свой инстанс Gotcha и заменить DSN в уже настроенном официальном Sentry SDK. Код приложения переписывать не нужно — тот же SDK просто отправляет данные на ваш сервер вместо sentry.io. Ниже — весь путь по шагам.

Нужно ли менять код приложения при переезде?

Нет. Gotcha не имеет собственного SDK: вы продолжаете использовать официальный Sentry SDK своего языка (PHP, Laravel, JavaScript/Node, браузерный JS, Python, Go). Меняется только строка DSN при инициализации — всё остальное (перехват исключений, breadcrumbs, теги, контексты) работает ровно так же, как описано в документации самого SDK. Gotcha просто оказывается на другом конце DSN.

Что нужно, чтобы поднять Gotcha

Gotcha — self-hosted сервис из трёх компонентов: Docker-образ приложения, PostgreSQL и ClickHouse. Ни Kafka, ни Redis не требуется. Быстрый старт — docker compose up -d; для масштабирования есть режимы --mode=ingest|web|uptime|probe|all. Полные требования, переменные окружения, бэкапы и обновления — на странице Установка и эксплуатация.

Как перенести приложение с Sentry на Gotcha

Поднимите инстанс Gotcha. Docker-образ + PostgreSQL + ClickHouse, docker compose up -d. Детали — Установка.
Зарегистрируйтесь. Откройте /register на своём инстансе. Первый пользователь всегда проходит регистрацию и получает права администратора.
Создайте организацию и проект. После первого входа /onboarding создаёт и организацию, и первый проект одной формой. Платформа проекта (Go/PHP/JS/…) — лишь подсказка для сниппетов, на приём данных она не влияет.
Скопируйте DSN проекта. После создания проекта откроется страница «Подключение» (/projects/<id>/setup) с готовым DSN вида https://<public_key>@<адрес_gotcha>/<id_проекта> — это тот же формат open-key DSN, который ждут официальные Sentry SDK.
Замените DSN в приложении. Подставьте новый DSN туда, где раньше стоял DSN от Sentry, — в Sentry.init(...), SENTRY_LARAVEL_DSN, переменную окружения и т. п. Больше ничего специфичного для Gotcha в коде не нужно.
Проверьте первое событие. Вызовите тестовую ошибку — в течение нескольких секунд она появится в разделе «Проблемы» проекта, с группировкой одинаковых ошибок в одну issue.
Настройте оповещения. В разделе «Оповещения» добавьте канал доставки (email, webhook или Telegram) и правила (новая проблема, регрессия, всплеск).

Готовые сниппеты установки и инициализации для каждого языка — на странице SDK и интеграции.

Пример: смена DSN (Python)

Единственная правка в коде — значение dsn. Было (Sentry Cloud):

sentry_sdk.init(
    dsn="https://<key>@o0.ingest.sentry.io/<project>",
    traces_sample_rate=0.2,
)

Стало (self-hosted Gotcha):

sentry_sdk.init(
    dsn="https://<public_key>@<адрес_gotcha>/<id_проекта>",
    traces_sample_rate=0.2,
)

Аналогично — для PHP/Laravel, JavaScript/Node, браузерного JS и Go: меняется только строка DSN. Полные примеры — SDK и интеграции.

Что переносится, а что настраивается заново

Сигнал / аспект	При переезде
Ошибки	Тот же Sentry SDK, только новый DSN. Работает сразу
Трейсинг / производительность	Тот же `traces_sample_rate` (`tracesSampleRate`). В браузере Web Vitals собираются автоматически
Профили	Через Sentry SDK (`profiles_sample_rate`) или «сырой» pprof на `POST /profiles/pprof`
Метрики	Не через Sentry SDK — по OTLP на `POST /v1/metrics` (Bearer с public_key). См. Метрики
`environment` / `release`	Переносятся как есть — те же поля SDK
Инфраструктура	Новое: свой инстанс (Docker + PostgreSQL + ClickHouse)
Оповещения	Настраиваются заново в разделе «Оповещения» вашего инстанса
Историческ. данные Sentry	Не мигрируют автоматически — Gotcha начинает собирать данные с момента подключения

Работают ли те же Sentry SDK без изменений?

Да — используются официальные Sentry SDK без форков и патчей. Gotcha реализует серверную сторону протокола приёма (envelope/store), поэтому SDK не отличает Gotcha от Sentry на уровне отправки. Это же означает, что откатиться обратно — тоже просто смена DSN.

Если событие не доходит после переезда

Самые частые причины — те же, что и при первом подключении Sentry SDK:

Причина	Как проверить
Неверный / отозванный DSN	Сверьте с «Настройки проекта → DSN-ключи»; ingest отвечает `401`/`403`
DSN от чужого проекта	`project_id` в DSN должен совпадать с проектом ключа (иначе `403`)
Сеть / файрвол	`curl -i <адрес_gotcha>/healthz` с той же машины, где работает приложение
Тело события слишком большое	По умолчанию лимит 1 МБ (`413` при превышении)
Короткий процесс не успел отправить	Вызовите `Flush`/`close` перед выходом (CLI, serverless, воркеры)
CSP в браузере	Добавьте адрес Gotcha в `connect-src`

Полный разбор — раздел «Если событие не доходит» на странице SDK и интеграции.

Что дальше

SDK и интеграции — сниппеты подключения для всех языков.
Установка и эксплуатация — поднять и обслуживать инстанс.
Первые шаги — сквозной путь от регистрации до первого оповещения.

Gotcha распространяется под лицензией Apache-2.0, исходный код открыт на GitHub и GitFlic.