API and Architecture

When deciding where new logic should live, default to server-side (Relay). Processing data in Relay keeps behavior consistent across SDK versions and avoids duplicating logic in clients that may remain deployed indefinitely.

Put logic in the SDK only when it genuinely needs to run client-side:

• It needs to run before data leaves the customer's application (e.g., user-controlled filtering like before_send_*)
• It requires access to platform-specific APIs
• It's strictly latency-sensitive
• It needs to function in offline scenarios

If data has already been collected, transform it in Relay.

SDKs typically outlive individual API versions. A user might stay on an SDK release for months or years, while server responses continue to evolve. SDKs MUST handle this gracefully:

• Ignore unknown fields, categories, or dimensions rather than erroring
• Tolerate missing optional fields
• Accept new enum values without crashing
• Handle rate limiting responses

The general principle: additive server-side changes MUST NOT break existing SDK versions.

Any change to public API — adding, modifying, deprecating, or removing — REQUIRES approval from an SDK Senior Engineer.

Public API includes anything a user can call, import, configure, subclass, or otherwise reference. When in doubt, check for usage in public repositories. If you're still unsure, treat it as public.

How each SDK detects API changes (CI snapshot diffs, etc.) varies by language, but the approval requirement applies everywhere.

Semantic conventions are shared across SDKs, ingest, and the product — treat them like public API. New attributes MUST be defined in sentry-conventions before SDK implementation. The process:

1. Open a PR to sentry-conventions
2. Get code owner approval
3. Wait at least 3 business days
4. Implement in the SDK

This ensures attributes are reviewed and consistent across the ecosystem before any SDK ships them.

Changes to existing attributes (renaming, removing, or changing semantics) are breaking changes and MUST follow the breaking change process. The sentry-conventions repo has its own deprecation lifecycle — deprecated attributes go through a backfill period (at least 90 days) before moving to normalize, and replacements and aliases MUST be maintained for both old and new names during the transition.

Breaking changes and deprecations are closely linked — every breaking change goes through a deprecation period first. Both follow a lifecycle designed to give users time and guidance to migrate.

Deprecation lifecycle

Deprecations of public APIs, integrations, and supported platforms follow three stages:

1. Announce in a minor release: add a runtime warning (where possible), update the changelog and docs, and publish a migration guide. Warnings MUST include the replacement, a code example, and a link to migration docs.
2. Keep it working for at least one subsequent minor release (e.g., deprecated in X.Y, still functional in X.(Y+1)).
3. Remove only in the next major release (X+1.0).

Deprecating an entire SDK follows a separate, more involved process — see the Deprecating an SDK playbook.

Breaking changes

Breaking changes MUST follow the breaking changes playbook. They can only ship in major versions; opt-in previews are allowed in minor versions.

Every breaking change MUST include:

• A migration guide with copy-pastable examples
• A changelog entry using the BREAKING CHANGE: notation
• Validation of the migration guide using an LLM to ensure clarity and completeness

Deprecation timelines can vary by SDK, but the stages and process apply everywhere.