How to migrate from Sentry to self-hosted Gotcha

2026-07-22 · By OtezVikentiy

Gotcha ingests events and transactions over the Sentry ingest protocol, so migrating from Sentry to self-hosted Gotcha comes down to one thing: stand up your own Gotcha instance and swap the DSN in your already-configured official Sentry SDK. You don’t rewrite application code — the same SDK simply sends data to your server instead of sentry.io. Here’s the full path, step by step.

Do you need to change application code to migrate?

No. Gotcha has no SDK of its own: you keep using the official Sentry SDK for your language (PHP, Laravel, JavaScript/Node, browser JS, Python, Go). Only the DSN string in the init call changes — everything else (exception capture, breadcrumbs, tags, contexts) behaves exactly as the SDK’s own docs describe. Gotcha just sits at the other end of the DSN.

What it takes to stand up Gotcha

Gotcha is a self-hosted service with three components: the application Docker image, PostgreSQL, and ClickHouse. No Kafka and no Redis. Quickstart is docker compose up -d; for scale-out there are --mode=ingest|web|uptime|probe|all modes. Full requirements, environment variables, backups, and upgrades are on the Installation page.

How to migrate an application from Sentry to Gotcha

1. Stand up a Gotcha instance. Docker image + PostgreSQL + ClickHouse, docker compose up -d. Details on Installation.
2. Register. Open /register on your instance. The first user always completes registration and becomes the instance administrator.
3. Create an organization and a project. After the first login, /onboarding creates both the org and the first project in one form. The project’s platform (Go/PHP/JS/…) is only a hint for snippets; it doesn’t affect ingestion.
4. Copy the project DSN. After creating the project you land on the Connect page (/projects/<id>/setup) with a ready DSN of the form https://<public_key>@<gotcha_host>/<project_id> — the same open-key DSN format the official Sentry SDKs expect.
5. Replace the DSN in your app. Drop the new DSN wherever the Sentry DSN used to be — Sentry.init(...), SENTRY_LARAVEL_DSN, an environment variable, and so on. Nothing else Gotcha-specific is needed in code.
6. Verify the first event. Trigger a test error — within seconds it appears under the project’s Issues, with identical errors grouped into one issue.
7. Set up alerts. In the Alerts section add a delivery channel (email, webhook, or Telegram) and rules (new issue, regression, spike).

Ready-to-paste install and init snippets per language are on the SDK & Integrations page.

Example: swapping the DSN (Python)

The only code change is the dsn value. Before (Sentry Cloud):

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

After (self-hosted Gotcha):

sentry_sdk.init(
    dsn="https://<public_key>@<gotcha_host>/<project_id>",
    traces_sample_rate=0.2,
)

It’s the same for PHP/Laravel, JavaScript/Node, browser JS, and Go: only the DSN string changes. Full examples: SDK & Integrations.

What carries over, what you set up again

Do the same Sentry SDKs work unchanged?

Yes — you use the official Sentry SDKs, no forks or patches. Gotcha implements the server side of the ingest protocol (envelope/store), so the SDK can’t tell Gotcha from Sentry at the send layer. That also means rolling back is just another DSN swap.

If events don’t arrive after the switch

The most common causes are the same as on any first Sentry SDK setup:

Full breakdown: the “If events don’t arrive” section on SDK & Integrations.

Next steps

• SDK & Integrations — connection snippets for every language.
• Installation — stand up and operate an instance.
• Getting Started — end to end from sign-up to first alert.

Gotcha is Apache-2.0 licensed, with source open on GitHub and GitFlic.