What “compatibility-first” means in error tracking

The definition

Compatibility-first error tracking is a design posture, not a checklist item.

A tool is compatibility-first when its primary design goal is accepting the wire format, SDK protocol, and REST surface of an existing, widely-deployed tool — in 2026, that tool is Sentry — so that teams can switch backends without changing their instrumented code. The instrumentation is the expensive part: the SDK calls scattered across services, the context and breadcrumb configuration, the release tagging in CI. Compatibility-first means all of that transfers. Only the destination changes.

The term matters because it names a real tradeoff in tool design. A backend either prioritizes accepting existing SDK output or it prioritizes a cleaner, forward-looking protocol (typically OTLP) and asks users to migrate their SDK configuration. Both choices are defensible. Compatibility-first is the choice that puts the user’s existing instrumentation investment above a fresh-start protocol preference.

The Sentry envelope format became the de facto standard for error-tracking ingest in the early 2010s when Sentry released its open-source server and SDKs for every major language. Tools like GlitchTip, Bugsink, and urgentry adopted the same envelope format so that existing Sentry SDK instrumentation would work without modification. That adoption is what makes “compatibility-first” a meaningful category rather than a marketing phrase: it describes a concrete architectural commitment with verifiable consequences.

The three compatibility surfaces

Compatibility-first covers three distinct surfaces, and a tool needs to honor all three to make the full claim.

SDK wire format

The SDK wire format is the HTTP protocol between the Sentry SDK and the ingest backend: the envelope POST to /api/<project_id>/envelope/, the X-Sentry-Auth header, the newline-delimited envelope body, and the item types within it (event, transaction, attachment, session, check-in).

When a compatible backend accepts this format, the SDK needs no modification. The DSN encodes the host and project ID; the SDK derives the endpoint from those fields and sends the same HTTP request it would send to Sentry. A backend that accepts the envelope at the right path with the right auth header gets events from any Sentry SDK version that speaks that envelope revision. This is the surface the DSN-swap test verifies.

Wire format compatibility is binary in practice: either the event lands or it does not. That makes it the clearest of the three surfaces to verify and the most consequential to fail.

REST API surface

The REST API surface is the set of documented Sentry REST endpoints that tools outside the SDK call: CI pipelines that create releases and upload source maps, dashboards that query issue counts, scripts that resolve issues in bulk, integrations that pull event data into other systems.

SDK wire format compatibility gets events into the backend. REST API compatibility keeps everything built around those events working: the CI release creation step, the source map upload, the issue resolution webhook, the Slack integration that queries issue counts. Without REST API compatibility, teams replace their SDK target but rebuild every integration from scratch.

The surface is large. Sentry’s public REST API documentation covers hundreds of operations across organizations, projects, issues, events, releases, and integrations. A compatibility-first tool counts its coverage explicitly. urgentry covers 218 of the 218 documented operations; the full matrix is at /sentry-alternative/.

OTLP intake

OTLP intake is the backend’s ability to accept events over the OpenTelemetry Protocol in addition to the Sentry envelope. This matters because many teams run OTel pipelines for distributed tracing and want a single backend that accepts both their Sentry SDK error events and their OTel span and log data.

OTLP intake is not a replacement for Sentry envelope acceptance in a compatibility-first tool; it is an addition. A tool that only accepts OTLP and asks users to switch their SDK initialization away from the Sentry SDK is not compatibility-first — it is a migration target. A compatibility-first tool accepts the Sentry envelope from existing SDK code and OTLP from OTel-instrumented code in the same binary, with no configuration split between the two ingest paths.

The OTLP surface that matters for error tracking is OTLP/HTTP, the HTTP/protobuf transport defined in the OpenTelemetry Protocol specification. An error-tracking backend that accepts OTLP traces and logs can perform the same fingerprinting and issue grouping on OTel exception span events that it performs on Sentry envelope events.

Why compatibility-first matters strategically

The user’s investment is in instrumented code, not in SDK configuration, and switching cost is the dominant lock-in factor in error tracking.

SDK initialization is a one-time act: a few lines of code in each service’s startup path. The instrumentation built on top of it accumulates over years: Sentry SDK calls in error handlers, breadcrumb recording in middleware, user context attachment in auth flows, custom fingerprinting rules, release tagging in deployment scripts. That instrumentation is the real cost. Changing the backend that receives it should not require touching any of it.

“Swap, don’t rewrite” names this precisely. A compatibility-first switch is an infrastructure change, not an engineering project. The team changes one environment variable per service, verifies events land, and moves on. No sprint to remove SDK calls and add OTel ones. No coordination with every team that owns an instrumented service. No quiet regressions from instrumentation points missed during the rewrite.

The strategic consequence is that compatibility-first makes the switching decision reversible. If the new backend does not work out, the DSN change reverts in minutes. Non-compatible migrations are not reversible in the same way: reverting a full SDK rewrite requires re-doing the engineering work in the other direction.

What it does not mean

Compatibility-first is a claim about protocol surfaces, not about product surfaces, and the distinction matters when evaluating tools.

It does not mean feature parity. A backend can accept every byte of the Sentry envelope format and still lack Sentry’s performance monitoring dashboards, session replay, cron monitor product, or project-level Ownership Rules UI. Those are product decisions unrelated to the wire-format contract. Evaluating a compatibility-first tool for feature parity requires the compatibility matrix, not the DSN-swap test.

It does not mean visual UI parity. The UI that surfaces grouped issues, alerts, and release data can differ substantially between a compatibility-first backend and Sentry. The contract is that the data arrives correctly, not that it looks the same once it arrives.

It does not mean every behavioral quirk. Some Sentry behaviors are undocumented or implementation-specific: edge cases in fingerprinting for certain stack frame shapes, response timing on large envelope batches, specific rate limit response codes. A compatibility-first tool targets the documented contract that the SDK and CI tooling rely on, not every incidental behavior of the Sentry implementation.

The useful framing: compatibility-first is a claim about the surfaces that SDK authors and CI authors write code against. If those surfaces work, the team’s instrumentation and automation transfers. Everything else is a separate evaluation.

How to verify a tool is actually compatibility-first

Claims of Sentry compatibility are common; verification is cheaper than taking them on faith.

The DSN-swap test. Stand up the candidate backend, copy its DSN, point one real service at it, throw one real error, and confirm the event lands with a readable stack trace, the breadcrumbs from the request, and the user context your SDK was sending. If it passes, the SDK wire format claim is verified for your specific SDK version and configuration. A candidate that fails this test is not compatibility-first regardless of what the marketing page says. The guide at /guides/evaluate/sentry-switch-proof/ walks each step.

The SDK version matrix test. Ask the vendor which Sentry SDK versions pass the DSN-swap test. Sentry SDK major versions differ in their envelope schema. Version 6 used the legacy /store/ endpoint. Version 7 introduced the envelope endpoint and dropped the secret key from the DSN format. Version 8 changed transaction sampling behavior. A tool that passes the test for the current SDK major version may silently fail for older SDK versions still running in long-lived services.

The REST endpoint count. Ask for a count of documented Sentry REST operations covered and a way to reproduce the count. A tool that says “full API compatibility” without a number is making an untestable claim. A tool with a source-scanned operation list mapped to its handlers is making a testable one.

The operator survey. Talk to teams already running the tool in production. The DSN-swap test passes on a laptop; production exposes edge cases in envelope parsing, auth header handling, and rate limit behavior. An operator who has run the backend against real traffic for six months knows which compatibility edges exist.

The compatibility-first vs OTel-native split

Some backends present themselves as Sentry alternatives while their primary design is OTel-native: they accept OTLP and provide Sentry SDK compatibility as a secondary, sometimes partial, path. That is a different product category.

The OTel-native approach is coherent. OpenTelemetry is the emerging standard for observability instrumentation, and a backend built around OTLP as its first-class protocol has cleaner semantics for trace context, metric correlation, and log attachment. The tradeoff is the migration cost: teams must rewrite SDK initialization from the Sentry SDK to the OTel SDK, update every service that uses Sentry-specific APIs (Sentry.captureException, Sentry.addBreadcrumb, custom fingerprinting rules), and accept that Sentry-specific SDK features may not map cleanly to OTel equivalents.

That is not a swap. That is a migration. Calling it compatibility-first misrepresents the engineering work the team will do.

Compatibility-first accepts both paths. The Sentry envelope arrives from existing instrumentation; OTLP arrives from new OTel instrumentation or OTel collectors already in the pipeline. The same backend performs issue grouping on both, stores them in the same project, and surfaces them in the same UI. Teams can migrate individual services to OTel at their own pace while the Sentry-SDK-instrumented services continue sending to the same backend without any change.

Where urgentry sits in this taxonomy

urgentry is Sentry-SDK-compatible by primary design, with OTLP/HTTP as a second ingest receiver in the same binary.

The primary ingest path accepts the Sentry SDK envelope format at the standard endpoint shape derived from the DSN. The SDK sends the same HTTP POST it would send to Sentry SaaS or Sentry self-hosted. No code changes, no SDK version constraints beyond the documented envelope revision support. The DSN is the only diff between a Sentry-instrumented service and an urgentry-instrumented one.

On the REST API surface, urgentry covers 218 of the 218 documented Sentry REST operations. The full list, with each operation mapped to its urgentry handler and the test that verifies it, is at /sentry-alternative/. That coverage means CI pipelines that create releases and upload source maps, integrations that query issue counts, and scripts that resolve issues in bulk all work against urgentry without modification.

The OTLP/HTTP receiver runs in the same binary as the Sentry envelope receiver. There is no separate deployment, no sidecar, no second process. Teams with an existing OTel collector pipeline point one additional exporter at urgentry’s OTLP endpoint; teams running Sentry SDKs change one environment variable. Both paths land events in the same project, grouped by the same fingerprinting logic, surfaced in the same UI.

The binary runs at 52 MB resident memory at 400 events per second on a single-core VPS. SQLite is the default storage backend; Postgres is available for teams that need it. The license is FSL-1.1-Apache-2.0, which converts to Apache 2.0 after two years.

The two cases where compatibility-first is worth less than it sounds

Compatibility-first is a strong argument when the team has existing Sentry SDK instrumentation it wants to preserve. In two specific cases, the category position offers less than it appears to.

You are already mid-migration off Sentry format. If the team has already committed to replacing Sentry SDK calls with OTel SDK calls across its services, the Sentry envelope compatibility of the candidate backend is irrelevant to the migration work in progress. The engineering effort is the same regardless of whether the destination backend accepts Sentry envelopes. In this case, evaluate backends on their OTLP support, issue grouping quality, and product surface — not on their Sentry compatibility.

Your team uses a custom in-house wire format. Some organizations built error ingest pipelines before the Sentry SDK became standard and never migrated. If events travel over a custom protocol to a custom backend, the Sentry compatibility of urgentry or any other tool does not reduce your switching cost. The switching cost is the migration to a standard wire format, which is a separate engineering project. Compatibility-first addresses the cost of switching backends, not the cost of standardizing on a protocol.

Outside these two cases, compatibility-first is the strongest available argument for why switching should be a short infrastructure task rather than a long engineering project.

Frequently asked questions