Java SDK Public API

---
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](https://github.com/Kotlin/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`)

See the `options` rule for how to add and wire up a new option.

### 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.