---

alwaysApply: false description: Public API surface, binary compatibility, and common classes to modify

Java SDK Public API

API Compatibility

Public API is tracked via .api files generated by the Binary Compatibility Validator Gradle plugin. Each module has its own file at <module>/api/<module>.api.

• Never edit .api files manually. Run ./gradlew apiDump to regenerate them.
• ./gradlew check validates current code against .api files and fails on unintended changes.
• @ApiStatus.Internal marks classes/methods as internal — they still appear in .api files but are not part of the public contract.
• @ApiStatus.Experimental marks API that may change in future versions.

Key Public API Classes

Entry Point

Sentry (sentry module) is the static entry point. Most public API methods on Sentry delegate to getCurrentScopes(). When adding a new method to Sentry, it typically calls through to IScopes.

Interfaces

| Interface | Description | |-----------|-------------| | IScope | Single scope — holds data (tags, extras, breadcrumbs, attributes, user, contexts, etc.) | | IScopes | Multi-scope container — manages global, isolation, and current scope; delegates capture calls to SentryClient | | ISpan | Performance span — timing, tags, data, measurements | | ITransaction | Top-level transaction — extends ISpan |

Configuration

SentryOptions is the base configuration class. Platform-specific subclasses:

• SentryAndroidOptions — Android-specific options
• Integration modules may add their own (e.g. SentrySpringProperties)

New features must be opt-in by default — add a getter/setter pair to the appropriate options class.

Internal Classes (Not Public API)

| Class | Description | |-------|-------------| | SentryClient | Sends events/envelopes to Sentry — receives captured data from Scopes | | SentryEnvelope / SentryEnvelopeItem | Low-level envelope serialization | | Scope | Concrete implementation of IScope | | Scopes | Concrete implementation of IScopes |

Adding New Public API

When adding a new method that users can call (e.g. a new scope operation), these classes typically need changes:

Interfaces and Static API

1. IScope — add the method signature
2. IScopes — add the method signature (usually delegates to a scope)
3. Sentry — add static method that calls getCurrentScopes()

Implementations

4. Scope — actual implementation with data storage
5. Scopes — delegates to the appropriate scope (global, isolation, or current based on defaultScopeType)
6. CombinedScopeView — defines how the three scope types combine for reads (merge, first-wins, or specific scope)

No-Op and Adapter Classes

7. NoOpScope — no-op stub for IScope
8. NoOpScopes — no-op stub for IScopes
9. ScopesAdapter — delegates to Sentry static API
10. HubAdapter — deprecated bridge from old IHub API
11. HubScopesWrapper — wraps IScopes as IHub

Serialization (if the data is sent to Sentry)

12. Add serialization/deserialization in the relevant data class or create a new one implementing JsonSerializable and JsonDeserializer

Tests

13. Write tests for all implementations, especially Scope, Scopes, SentryTest, and any new data classes
14. No-op classes typically don't need separate tests unless they have non-trivial logic

Protocol / Data Model Classes

Classes in the io.sentry.protocol package represent the Sentry event protocol. They implement JsonSerializable for serialization and have a companion Deserializer class implementing JsonDeserializer. When adding new fields to protocol classes, update both serialization and deserialization.

Namespaced APIs

Newer features are namespaced under Sentry.<feature>() rather than added directly to Sentry. Each namespaced API has an interface, implementation, and no-op. Examples:

• Sentry.logger() → ILoggerApi / LoggerApi / NoOpLoggerApi (structured logging, io.sentry.logger package)
• Sentry.metrics() → IMetricsApi / MetricsApi / NoOpMetricsApi (metrics)

Options for namespaced features are similarly nested under SentryOptions, e.g. SentryOptions.getMetrics(), SentryOptions.getLogs().

These APIs may share infrastructure like the type system (SentryAttributeType.inferFrom()) — changes to shared components (e.g. attribute types) may require updates across multiple namespaced APIs.