Sentry compatibility checklist: validate before you cutover.

Why a written checklist exists

The migration that goes wrong is almost never the one where the SDK stops talking to the server. That failure is loud and immediate. The migration that goes wrong is the one where the on-call engineer opens the new error tracker at midnight and discovers that the alert rule for “payment service error rate > 1%” never fired, because nobody recreated it.

A written checklist produces two things that verbal agreements do not: a record of what was confirmed, and a record of what was consciously skipped. Both matter. The things you confirmed give the team confidence to cut over. The things you skipped become the post-cutover backlog, with an owner and a deadline.

Work through this checklist before the cutover meeting, not during it. Bring the completed document. If a category has gaps, the meeting can decide whether those gaps block the cutover or get assigned to someone with a due date.

Before you start: set up a parallel environment

The most reliable way to run this checklist is with both Sentry and urgentry receiving live events at the same time. Configure urgentry as a second DSN target in the SDK for at least one service, run both for a few days, and compare the results category by category.

If you cannot run both in parallel, the minimum is a staging or pre-production environment pointed at urgentry with representative traffic. Synthetic testing catches less than real traffic does. Use real traffic where possible.

urgentry ships as a single binary. You can stand up a parallel instance in under ten minutes:

curl -fsSL https://urgentry.io/install.sh | sh
urgentry serve --role=all

The first run creates a default admin credential and a data directory. Create a project, copy the DSN, and add it as a second target in your SDK init. You are now running in parallel.

Category 1: SDK surface

Start here. Everything downstream depends on events reaching urgentry in a form it can parse and process.

Checklist

• Envelope endpoint. Confirm your SDK version sends to /api/{project_id}/envelope/. SDKs older than roughly 2020 may use the legacy /api/store/ endpoint instead. urgentry supports both, but verify which path your SDK takes by enabling SDK debug logging and watching the outbound request URL.
• Transport layer. Confirm the SDK is using the standard HTTP transport, not a custom transport that routes internally. Custom transports that bypass the SDK’s HTTP layer need to be re-pointed at urgentry directly and are outside the scope of this checklist.
• DSN swap confirmed. Set the urgentry DSN in the SDK init and restart the process. Verify the SDK is sending to the urgentry host, not to sentry.io. Check the SDK debug log or watch outbound traffic with a proxy tool.
• Sampling configuration preserved. If your SDK has a traces_sample_rate, profiles_sample_rate, or event-level sampling configured, confirm those values are present and correct in the urgentry DSN configuration as well. Sampling configuration lives in the SDK init, not in the server, so it transfers automatically when the DSN transfers.
• Performance integrations enabled. If your SDK init lists specific integrations (Django middleware, Express middleware, database query tracing), confirm they are still active after the DSN swap. The swap should not affect them, but verify.
• Release and environment tags correct. Trigger one error and confirm the release and environment values appear correctly on the urgentry event. A misconfigured release string is the most common cause of source map and symbolication failures downstream.

Sign-off criterion

At least one real error from your production or staging service appears in urgentry with the correct environment, release, and tag values. Stack trace is readable. Breadcrumbs are present. This is the same bar as the switch proof; if you have already run the switch proof, this category passes.

Category 2: Ingest endpoints

Beyond the main SDK ingest path, your deployment may use several other endpoints. Check each one that applies to your stack.

Checklist

• Source map uploads. urgentry exposes the same source map upload endpoint as Sentry. If your CI pipeline uploads source maps with sentry-cli, the only change is the --url flag pointing at your urgentry host. Confirm that a recent deploy with source maps produces readable stack traces in urgentry, not just raw minified positions.
• ProGuard and R8 mappings. For Android projects, confirm the ProGuard mapping upload step in your CI points at urgentry. The endpoint is API-compatible. Verify a crash from an obfuscated build appears with deobfuscated method names.
• Debug files (dSYM, DWARF, Breakpad). For iOS, macOS, and native Linux/Windows builds, confirm debug symbol uploads are re-pointed at urgentry. A native crash with missing symbols produces an unreadable stack trace; this is the most common gap in native crash workflows and the most time-consuming to discover post-cutover.
• Native crash minidumps. urgentry handles minidump ingest. If your native applications submit minidumps directly (not via the Sentry SDK), confirm the minidump endpoint URL is updated.
• OTLP/HTTP traces and logs. If you plan to use urgentry’s native OTLP support, confirm the OTLP endpoint is reachable from your services. urgentry handles OTLP in the same binary as Sentry SDK ingest; no separate collector is required. The OTLP port defaults to 4318 (HTTP).
• Cron job check-ins. If you monitor cron jobs or scheduled tasks via Sentry’s monitor check-in API, verify that urgentry’s monitor endpoint accepts the same payload format and that your check-in calls are re-pointed.
• Relay / client-side proxy. If your architecture routes SDK traffic through Sentry Relay, confirm whether urgentry’s ingest accepts Relay-forwarded traffic directly, or whether you plan to decommission the Relay hop. Running Sentry Relay in front of urgentry is not a tested configuration.

Sign-off criterion

Every ingest path your organization uses either (a) confirmed working against urgentry with a test upload or event, or (b) documented as a known gap with an owner and a date.

Category 3: Event processing

Events arriving at urgentry go through processing: grouping, symbolication, source map application, user context enrichment, and tag indexing. Each of these has configuration that does not transfer automatically from Sentry.

Checklist

• Issue grouping fingerprints. If your Sentry configuration uses custom fingerprinting rules, migrate those rules to urgentry’s fingerprinting configuration before cutting over. urgentry uses the same fingerprint variable syntax as Sentry. Default grouping (stack trace hash) transfers automatically.
• Inbound filters. Sentry’s inbound filters (browser extension errors, localhost events, known bots) are project-level settings. Recreate any filters you rely on in urgentry’s project settings. A missing filter means events you were previously discarding will start appearing in the issue list.
• Server-side sampling rules. If you configured server-side dynamic sampling in Sentry (not just SDK-side), recreate equivalent rules in urgentry. Note: urgentry’s sampling UI differs from Sentry’s; review the configuration surface before assuming parity.
• Source map application confirmed. After uploading source maps (from Category 2), open a recent JavaScript error in urgentry and verify that the stack trace shows original file paths and line numbers, not minified positions. If the stack is still minified, the upload succeeded but the version string does not match the release tag on the event. Check the release value in your SDK init.
• User context rendering. Open an event that your SDK was populating with user context (ID, email, username). Confirm those fields appear correctly on the urgentry event detail page.
• Performance trace linking. If your SDK sends both errors and performance traces, confirm that urgentry links them in the event detail view. Open an error that occurred during a traced request and verify the trace ID is present and links to the associated span.
• Tag cardinality. If any of your services attach high-cardinality tags (request IDs, per-user identifiers), confirm that urgentry’s tag index does not grow unbounded. Set a tag cardinality cap in urgentry’s project settings if you have tags with more than a few hundred distinct values.

Sign-off criterion

Errors from your real services produce readable stack traces with correct source positions. Fingerprinting produces the grouping behavior you expect. User context appears on events. Performance traces link to associated errors.

Category 4: Alerts and notifications

Alert rules are the highest-risk category. They are the part of Sentry your team will notice is missing the moment an incident starts. They are also the part most likely to be “configured in Sentry somewhere” without anyone knowing the full list.

Checklist

• Export your current Sentry alert rules. Before you do anything else in this category, pull the full list of alert rules from Sentry’s API or settings UI. Document every rule: the trigger condition, the threshold, the notification channel, and the owner. This list will surprise you. Most teams have more rules than they remember.
• Triage: must-have vs. informational. For each rule, decide whether it is on-call-critical (must fire, must page, lives in PagerDuty), team-informational (Slack notification, nice to have), or legacy (was created, never reviewed, can be removed). Only the first category is a blocking requirement for cutover.
• Recreate on-call-critical rules in urgentry. Create each must-have rule in urgentry’s alert configuration. Verify the trigger condition matches. Trigger a test event that satisfies the condition and confirm the notification reaches its destination.
• Slack and email channels confirmed. Urgentry supports Slack and email alert destinations. Confirm the webhook URL (for Slack) or SMTP configuration (for email) is set and that a test alert reaches the channel.
• PagerDuty and OpsGenie routes. If your on-call setup routes through PagerDuty or OpsGenie, confirm urgentry’s webhook output format matches what your routing rules expect. Test with a real alert trigger, not just a webhook ping.
• “New issue” vs. “regression” trigger behavior. urgentry fires on “new issue” by default. A second occurrence of the same fingerprint does not retrigger. If any of your Sentry rules use the “regression” trigger (an issue resolves and then reappears), confirm urgentry’s equivalent behavior and recreate the rule accordingly.
• Issue ownership rules. If your Sentry project uses code-owner or team-ownership rules to route alerts to specific people, confirm whether those rules need to be recreated in urgentry. The ownership rule syntax is similar but not identical.
• Mute windows and scheduled downtime. If you mute alerts during deployments or maintenance windows, document the mechanism in urgentry. Urgentry’s mute and snooze behavior should be verified before the first production deployment after cutover.

Sign-off criterion

Every on-call-critical alert rule fires a test notification to its destination before the cutover. The full alert rule list is documented, with each rule marked as recreated, deferred, or removed. No rule is “unknown.”

Category 5: UI and workflow

The people who use the error tracker every day will notice differences in the UI faster than any automated test. Walk through the core workflows your team actually uses, not the full feature list.

Checklist

• Issue triage workflow. Open a real issue in urgentry. Assign it to a team member. Mark it as resolved. Verify the resolved status persists and that the issue does not reappear until a genuinely new event arrives. Walk the same triage steps your team uses in Sentry.
• Search and filtering. Run the searches your team uses most often: by user, by environment, by release, by tag value. Confirm the results match expectations. urgentry’s query syntax follows Sentry’s query language; most queries transfer without changes.
• Saved views and dashboards. If your team relies on saved Sentry searches or Discover dashboards for daily monitoring, those do not transfer automatically. Decide which saved views to recreate in urgentry before the cutover so the team does not land in a blank slate.
• Release tracking. If your team tracks releases in Sentry (deploy notifications, first-seen-in-release, regression detection), verify the release workflow in urgentry. The release tag on events is the anchor; confirm CI sends release deploy notifications via the Sentry-compatible releases API endpoint.
• Performance transaction views. If your team uses Sentry’s performance views to monitor p95 latency or identify slow transactions, open a few real transactions in urgentry’s performance UI and verify the waterfall view and span details render correctly.
• Session replay. urgentry’s session replay implementation is partial. If your team uses replay as a standard triage step for front-end bugs, test it explicitly with real sessions before treating it as equivalent to Sentry’s replay. Specific gaps are documented in the compatibility matrix. If replay is a non-negotiable workflow tool, put the evaluation here in writing before the cutover meeting.
• Profiling. urgentry’s profiling surface is partial, similar to replay. If continuous profiling is a core part of your production workflow, validate it against the compatibility matrix and test with a representative workload. Treat it as a known gap unless testing confirms parity.
• User roles and permissions. Urgentry has organization and project-level roles. Confirm that the access model fits your team structure. If you have auditors or read-only stakeholders with Sentry access, recreate those roles in urgentry.

Sign-off criterion

The primary triage workflow (find issue, read stack, assign, resolve) works end to end for at least one person on the on-call rotation. Every UI gap that does not meet Sentry parity is documented and tagged as either blocking or post-cutover backlog.

Category 6: Retention

Retention is the category most commonly skipped in migration planning and the most likely to cause a compliance problem three months later.

Checklist

• Event retention window. Confirm the event retention window in urgentry’s project settings. The default may differ from what your Sentry plan provided. If your security team or compliance framework specifies a minimum or maximum retention period, set it explicitly and document the setting.
• Attachment retention. Source maps, debug files, and minidumps are stored separately from events. Confirm the attachment retention window is set correctly. Large debug file sets will grow disk usage faster than raw events.
• PII and data scrubbing. If your Sentry configuration had PII scrubbing rules (credit card patterns, email addresses, custom regexes), recreate those rules in urgentry’s data scrubbing settings. An unconfigured scrubbing rule means PII that was scrubbed in Sentry will appear in urgentry event payloads.
• Disk capacity planning. Unlike hosted Sentry, urgentry uses your disk. Calculate the expected disk growth from event volume, attachment size, and your chosen retention window. For a typical mid-size web service with source maps, a 90-day retention window, and moderate traffic, plan for 20–100 GB of storage. Run out of disk, and ingest stops.
• Backup strategy confirmed. urgentry uses SQLite by default. Confirm continuous backup is configured before the cutover. Litestream is the standard tool; it replicates WAL frames to an S3-compatible bucket continuously. Test the restore path before you need it.
• Postgres mode (if applicable). If your deployment uses Postgres rather than SQLite, confirm the backup and retention configuration at the Postgres level. The urgentry-level retention window controls how long urgentry keeps events in the database; Postgres-level backup controls recovery from host failure.

Sign-off criterion

Event retention, attachment retention, and PII scrubbing are configured and documented. A backup restore has been tested at least once. Disk capacity projection is written down and reviewed by whoever manages the host.

Category 7: Third-party integrations

Sentry’s integration ecosystem is large. The specific integrations your organization uses vary. Work through your actual list, not the full catalog.

Checklist

• Audit your active Sentry integrations. Open Sentry’s Settings ’ Integrations page and list every active integration. For each one, decide whether urgentry needs a comparable integration for the cutover to be safe, or whether it can wait.
• GitHub and GitLab commit linking. If your team uses Sentry’s commit-linking feature (a commit in the stack trace links back to the GitHub diff), configure the same SCM integration in urgentry. Confirm the link works on a real event with a known release commit.
• Jira and Linear issue sync. If Sentry creates Jira or Linear issues automatically from new Sentry issues, replicate that workflow in urgentry. Urgentry’s webhook output can drive a Zapier, Make, or custom webhook handler that creates issues in your project tracker.
• CI/CD deploy notifications. If your CI pipeline sends release and deploy data to Sentry via sentry-cli releases deploys new, update the --url flag to point at urgentry. The API surface is compatible.
• Uptime monitoring. If you use Sentry’s uptime monitoring alongside error tracking, confirm whether urgentry’s equivalent feature covers the same endpoints and notification paths. If it does not, document the external uptime monitoring tool you will use instead.
• Webhook consumers. If any internal tooling consumes Sentry webhooks (build systems, escalation scripts, dashboards), confirm the urgentry webhook payload format is compatible, or update the consumers before the cutover.
• Single sign-on (SSO). If your team authenticates to Sentry via SAML or OAuth, configure urgentry’s SSO settings before the cutover so the team does not need to manage a separate password.

Sign-off criterion

Every integration your team depends on for daily work is either confirmed working in urgentry or documented as a known gap with a plan. No integration is in an unknown state on cutover day.

How to run the tests

The checklist above tells you what to verify. Here is how to verify it efficiently.

Use a parallel DSN for ingest validation

In most Sentry SDKs, you can supply only one DSN. The simplest workaround is to run a thin HTTP proxy that forwards ingest requests to both Sentry and urgentry. Alternatively, deploy one non-critical service with its DSN pointing exclusively at urgentry for the evaluation window. Either approach gives you real traffic without touching production.

Trigger test events deliberately

Most SDKs expose a captureException or captureMessage call you can invoke from a test endpoint or script. Use a real exception class, not just a string, so the stack trace is meaningful. For alert testing, raise exceptions that match your alert rule thresholds.

Smoke test each alert rule manually

For each on-call-critical alert rule, trigger the exact condition the rule watches for. Watch the urgentry alert log and confirm the notification arrives within the expected time window. Do not assume an alert fires because the rule was created; test it.

Verify source maps with a known error

The cleanest source map test is an error you have seen before in Sentry with a readable stack. Trigger the same error against urgentry and compare the stack traces side by side. If urgentry’s stack shows minified positions where Sentry showed original positions, the source map upload or release version string is mismatched.

Walk the triage flow with a real team member

Ask one engineer from the on-call rotation to triage a real issue in urgentry without guidance. Watch where they get stuck. The places they stop and look confused are the places the UI differs enough from Sentry to need documentation or training.

Sign-off criteria summary

The cutover is ready when all of the following are true:

• A real event from a real service appears in urgentry with a readable stack, correct environment and release values, and populated user context.
• Every on-call-critical alert rule fires a test notification to its destination.
• Source maps (or debug symbols) produce readable stacks for at least one symbolicated error type in your stack.
• Retention window, PII scrubbing, and backup are configured and documented.
• The primary triage workflow works end to end for at least one on-call engineer.
• Every checklist gap is recorded in a document with an owner and a date.

Present this document at the cutover meeting. The meeting should take fifteen minutes if the checklist is complete. If it takes longer, the preparation was not done.

When urgentry is not the right pick

This checklist is written for teams evaluating urgentry. The honest version of that evaluation includes the cases where urgentry is the wrong answer.

• Full session replay is non-negotiable. urgentry’s replay implementation is partial. If replay is a primary triage tool and you need parity with Sentry’s replay on day one, urgentry is not ready for that use case today.
• Native crash processing at scale. The minidump and native symbolication workflows work, but they have a narrower product surface than Sentry’s. If native crash processing is your primary use case and you process more than a handful of crashes per hour, test it thoroughly before committing.
• Zero ops capacity. urgentry requires a host, a backup strategy, and periodic maintenance. If your team has no one willing to own a server, hosted Sentry or another managed option is the right answer regardless of the bill.
• Compliance mandates a vendor-managed control plane. Some HIPAA and FedRAMP shapes require that the vendor holds the keys. A self-hosted tool does not satisfy that requirement.