The Sentry switch proof: one DSN, one event, one workflow.

Why the switch proof matters

The hardest part of moving off Sentry is not the destination tool. It is the assumption that something subtle in your SDK setup will break in production after the cutover, and you will not find it until 2 a.m. on a Tuesday. That fear is reasonable. It is also testable.

The switch proof is the test. It is small enough to run on a laptop, short enough to fit in a coffee break, and concrete enough that the result is not a matter of opinion. Either the event lands or it does not.

Run it before you write a doc. Run it before you schedule the meeting. Run it before you read the next comparison article.

What you need before you start

The shopping list is short.

• A laptop with either Docker or a Go 1.22+ toolchain.
• A real service that already sends events to Sentry. The proof is meaningful only if it uses your actual SDK, your actual configuration, and your actual code path.
• Ten minutes of attention. The steps are sequential, and skipping them creates ambiguous results.

You do not need to touch the existing Sentry installation. You do not need to disable any alerts. You do not need to coordinate with anyone. The proof is local to your machine.

Step 1: Stand up urgentry locally

The fastest path is the install script.

curl -fsSL https://urgentry.io/install.sh | sh
urgentry --config /tmp/urgentry-proof.yaml &

If you prefer Docker:

docker run -p 8000:8000 -v urgentry-data:/var/lib/urgentry \
  ghcr.io/urgentry/urgentry:latest

Either way, you should see urgentry serving on localhost:8000 within a few seconds. Open the URL in a browser. The first-run flow asks you to set an admin password and confirm the install. Do that and continue.

If the first run does not complete, stop here. The proof is not about debugging your laptop’s Docker setup. Either install the Go binary directly or read the install troubleshooting docs before continuing.

Step 2: Create a project and grab the DSN

In the urgentry UI, create an organization and one project. Pick the SDK that matches the service you plan to point at this instance — the choice changes the example snippets, nothing else.

The project settings page shows a DSN that looks like:

https://<public_key>@localhost:8000/<project_id>

Copy it. This DSN is the entire contract between your SDK and urgentry. Treat it the same way you would treat a Sentry DSN: it identifies the project and authenticates ingest.

Step 3: Swap the DSN in your real service

Open the service you picked. Find where the Sentry SDK is initialized. In most stacks, this is one line:

// Go
sentry.Init(sentry.ClientOptions{
    Dsn: os.Getenv("SENTRY_DSN"),
})

// Python
sentry_sdk.init(dsn=os.environ["SENTRY_DSN"])

// Node.js / browser
Sentry.init({ dsn: process.env.SENTRY_DSN });

For the proof, set SENTRY_DSN to the urgentry DSN you copied. Do not change the SDK version, the integration list, the sampling configuration, or anything else. The point is to prove that nothing else needs to change.

If your team uses a different environment variable name, the same rule applies: change the value, not the code.

Step 4: Throw a real error

Run the service. Trigger an error path you have used before — a known failing endpoint, a deliberately bad input, or a manually-raised exception in a worker. Avoid synthetic captureMessage("hello") calls. The proof is more useful when the event has a real stack trace from real code.

If you do not have a convenient failure path, the safest synthetic option is a deliberate division by zero or a null dereference inside a normal request handler. That gets you a realistic stack while still being deterministic.

Step 5: Confirm the event in the urgentry UI

Refresh the project’s Issues page. The event should appear within a few seconds. Open it and check:

• The stack trace is readable, with function names and file paths.
• The environment, release, and tags are populated correctly.
• Breadcrumbs from the request, if any, are present.
• User context, if your SDK was sending it, is attached.

If all four are clean, your SDK is talking to urgentry the same way it talks to Sentry. That is the proof. If any of them is missing or malformed, do not assume the proof failed yet — the SDK’s symbolication or context handling may need configuration that was implicit on the Sentry side. Check the troubleshooting section before drawing conclusions.

Step 6: Send a test alert

The event arriving is half the proof. The other half is the alert path. Without it, you have a passive log; with it, you have an error tracker.

In urgentry, open the project’s Alerts settings and add a webhook or email rule that fires on new issues. Trigger another error in the same service. Confirm the alert reaches the destination you configured. If you use Slack, this is the right place to test the Slack integration; if you use PagerDuty, same.

The alert path is where most error-tracker migrations actually quietly fail. Treat this step as mandatory, not optional.

What the proof tells you

A passing proof gives you four concrete facts:

• Your SDK speaks the protocol urgentry implements, with no code changes.
• Your existing instrumentation surface — environments, releases, tags, user context — transfers cleanly.
• The alert path your team relies on can be reconstructed in urgentry.
• The local install works, which is the same install you would run on a real server.

What it does not tell you:

• How urgentry behaves at production traffic. That is what a side-by-side evaluation answers.
• Whether every product surface you use in Sentry is present. That is what the compatibility matrix answers.
• Whether your team will prefer the urgentry UI. That is what running it for a week answers.

The proof is the gate, not the migration.

If the proof did not pass

The most common failure modes, in order:

The event never reached urgentry

Check the SDK’s own debug log. Most Sentry SDKs accept a debug=True flag that prints the request the SDK is about to send. If you see the SDK trying to reach sentry.io instead of localhost:8000, the DSN swap did not take effect. Restart the process; verify the environment variable.

If the SDK is reaching the right host but getting a non-2xx response, look at urgentry’s log. The error message will name the problem — project not found, DSN key invalid, payload rejected.

The event reached urgentry but the stack trace is empty

This is almost always source-map or symbolication configuration. For JavaScript, upload source maps in the same way you would for Sentry; the upload endpoint is API-compatible. For native code, upload debug files. The SDK is sending what it normally sends; urgentry is doing what Sentry would do, which is wait for the symbol artifacts.

The alert did not fire

Confirm the rule’s match condition. The default urgentry rule fires on “new issue,” which means a second occurrence of the same fingerprint will not retrigger. Test with a deliberately different error.

What to do after a passing proof

You now have enough evidence to schedule the conversation that matters. Bring the proof to it. The shape of that conversation is usually:

1. Show the working proof on a laptop.
2. Walk through the capability matrix for the surfaces your team uses.
3. Agree on a side-by-side evaluation window — one service, one week, both DSNs configured in parallel.
4. Define what “cutover-ready” looks like in writing: which alerts must fire, which dashboards must populate, which retention boundaries must hold.

The proof is the cheapest possible reduction in migration risk. Run it before any of the rest.

What this guide is not

This is not a cutover guide. The proof verifies that the SDK-to-server contract works. It does not migrate historical data, switch your alerting destinations, or reconfigure your CI/CD release tagging. Those are real steps and they belong to a separate, longer guide.

It is also not a recommendation to do the proof and immediately move. The recommendation is to do the proof first so the rest of the decision is grounded in something you have seen, not something you have read.