Merge branch 'main' into feat/samples-scope-attributes

Author: adinauer

.claude/skills/create-java-pr/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: create-java-pr
+description: Create a pull request in sentry-java. Use when asked to "create pr", "prepare pr", "prep pr", "open pr", "ready for pr", "prepare for review", "finalize changes". Handles branch creation, code formatting, API dump, committing, pushing, PR creation, and changelog.
+---
+
+# Create Pull Request (sentry-java)
+
+Prepare local changes and create a pull request for the sentry-java repo.
+
+## Step 1: Ensure Feature Branch
+
+```bash
+git branch --show-current
+```
+
+If on `main` or `master`, create and switch to a new branch:
+
+```bash
+git checkout -b <type>/<short-description>
+```
+
+Derive the branch name from the changes being made. Use `feat/`, `fix/`, `ref/`, etc. matching the commit type conventions.
+
+## Step 2: Format Code and Regenerate API Files
+
+```bash
+./gradlew spotlessApply apiDump
+```
+
+This is **required** before every PR in this repo. It formats all Java/Kotlin code via Spotless and regenerates the `.api` binary compatibility files.
+
+If the command fails, diagnose and fix the issue before continuing.
+
+## Step 3: Commit Changes
+
+Check for uncommitted changes:
+
+```bash
+git status --porcelain
+```
+
+If there are uncommitted changes, invoke the `sentry-skills:commit` skill to stage and commit them following Sentry conventions.
+
+**Important:** When staging, ignore changes that are only relevant for local testing and should not be part of the PR. Common examples:
+
+| Ignore Pattern | Reason |
+|---|---|
+| Hardcoded booleans flipped for testing | Local debug toggles |
+| Sample app config changes (`sentry-samples/`) | Local testing configuration |
+| `.env` or credentials files | Secrets |
+
+Restore these files before committing:
+
+```bash
+git checkout -- <file-to-restore>
+```
+
+## Step 4: Push the Branch
+
+```bash
+git push -u origin HEAD
+```
+
+If the push fails due to diverged history, ask the user how to proceed rather than force-pushing.
+
+## Step 5: Create PR
+
+Invoke the `sentry-skills:create-pr` skill to create a draft PR. When providing the PR body, use the repo's PR template structure from `.github/pull_request_template.md`:
+
+```
+## :scroll: Description
+<Describe the changes in detail>
+
+## :bulb: Motivation and Context
+<Why is this change required? What problem does it solve?>
+
+## :green_heart: How did you test it?
+<Describe how you tested>
+
+## :pencil: Checklist
+- [ ] I added GH Issue ID _&_ Linear ID
+- [ ] I added tests to verify the changes.
+- [ ] No new PII added or SDK only sends newly added PII if `sendDefaultPII` is enabled.
+- [ ] I updated the docs if needed.
+- [ ] I updated the wizard if needed.
+- [ ] Review from the native team if needed.
+- [ ] No breaking change or entry added to the changelog.
+- [ ] No breaking change for hybrid SDKs or communicated to hybrid SDKs.
+
+## :crystal_ball: Next steps
+```
+
+Fill in each section based on the changes being PR'd. Check any checklist items that apply.
+
+Then continue to Step 6.
+
+## Step 6: Update Changelog
+
+After the PR is created, add an entry to `CHANGELOG.md` under the `## Unreleased` section.
+
+### Determine the subsection
+
+| Change Type | Subsection |
+|---|---|
+| New feature | `### Features` |
+| Bug fix | `### Fixes` |
+| Refactoring, internal cleanup | `### Internal` |
+| Dependency update | `### Dependencies` |
+
+Create the subsection under `## Unreleased` if it does not already exist.
+
+### Entry format
+
+```markdown
+- <Short description of the change> ([#<PR_NUMBER>](https://github.com/getsentry/sentry-java/pull/<PR_NUMBER>))
+```
+
+Use the PR number returned by `sentry-skills:create-pr`. Match the style of existing entries — sentence case, ending with the PR link, no trailing period.
+
+### Commit and push
+
+Stage `CHANGELOG.md`, commit with message `changelog`, and push:
+
+```bash
+git add CHANGELOG.md
+git commit -m "changelog"
+git push
+```

.craft.yml

@@ -48,6 +48,8 @@ targets:
       maven:io.sentry:sentry-opentelemetry-agentless-spring:
       maven:io.sentry:sentry-opentelemetry-bootstrap:
       maven:io.sentry:sentry-opentelemetry-core:
+#      maven:io.sentry:sentry-opentelemetry-otlp:
+#      maven:io.sentry:sentry-opentelemetry-otlp-spring:
       maven:io.sentry:sentry-apollo:
       maven:io.sentry:sentry-jdbc:
       maven:io.sentry:sentry-graphql:

.cursor/rules/api.mdc

@@ -0,0 +1,89 @@
+---
+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`)
+
+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.

.cursor/rules/opentelemetry.mdc

@@ -14,6 +14,8 @@ The Sentry Java SDK provides comprehensive OpenTelemetry integration through mul
 - `sentry-opentelemetry-agentless-spring`: Spring-specific agentless integration
 - `sentry-opentelemetry-bootstrap`: Classes that go into the bootstrap classloader when the agent is used. For agentless they are simply used in the applications classloader.
 - `sentry-opentelemetry-agentcustomization`: Classes that help wire up Sentry in OpenTelemetry. These land in the agent classloader when the agent is used. For agentless they are simply used in the application classloader.
+- `sentry-opentelemetry-otlp`: Classes for using OpenTelemetry to send spans to Sentry using the OTLP endpoint and have Sentry use OpenTelemetry trace and span id.
+- `sentry-opentelemetry-otlp-spring`: Spring Boot convenience module that includes `sentry-opentelemetry-otlp` and the OpenTelemetry Spring Boot starter as transitive dependencies.
 
 ## Advantages over using Sentry without OpenTelemetry
 
@@ -86,3 +88,10 @@ After creating the transaction with child spans `SentrySpanExporter` uses Sentry
 ## Troubleshooting
 
 To debug forking of `Scopes`, we added a reference to `parent` `Scopes` and a `creator` String to store the reason why `Scopes` were created or forked.
+
+# OTLP
+When using `sentry-opentelemetry-otlp`, Sentry only loads trace ID and span ID from OpenTelemetry `Context` (via `OpenTelemetryOtlpEventProcessor`). Sentry does not rely on OpenTelemetry `Context` for scope storage and propagation, instead relying on its `DefaultScopesStorage`.
+It is common to keep Performance in Sentry SDK disabled since that part is taken over by OpenTelemetry.
+The `sentry-opentelemetry-otlp` module is not connected to the other `sentry-opentelemetry-*` modules but instead intended only when the goal is to run OpenTelemetry for creating spans and Sentry for other products like errors, logs, metrics etc.
+The `sentry-opentelemetry-otlp-spring` module wraps `sentry-opentelemetry-otlp` and includes the OpenTelemetry Spring Boot starter for easier setup in Spring Boot applications.
+The OTLP module does not easily work with the OpenTelemetry agent as it would require customizing the agent.JAR in order to get the propagator loaded.

.cursor/rules/options.mdc

@@ -0,0 +1,115 @@
+---
+alwaysApply: false
+description: Adding and modifying SDK options
+---
+# Adding Options to the SDK
+
+New features must be **opt-in by default**. Options control whether a feature is enabled and how it behaves.
+
+## Namespaced Options
+
+Newer features use namespaced option classes nested inside `SentryOptions`, e.g.:
+- `SentryOptions.getLogs()` → `SentryOptions.Logs`
+- `SentryOptions.getMetrics()` → `SentryOptions.Metrics`
+
+Each namespaced options class is a `public static final class` inside `SentryOptions` with its own fields, getters/setters, and callbacks (e.g. `BeforeSendLogCallback`, `BeforeSendMetricCallback`).
+
+A typical namespaced options class contains:
+- `enabled` boolean (default `false` for opt-in)
+- `sampleRate` double (if the feature supports sampling)
+- `beforeSend` callback interface (nested inside the options class)
+
+To add a new namespaced options class:
+1. Create the `public static final class` inside `SentryOptions` with fields, getters/setters, and any callback interfaces
+2. Add a private field on `SentryOptions` initialized with `new SentryOptions.MyFeature()`
+3. Add getter/setter on `SentryOptions` annotated with `@ApiStatus.Experimental`
+
+## Direct (Non-Namespaced) Options
+
+Options that apply globally across the SDK (e.g. `dsn`, `environment`, `release`, `sampleRate`, `maxBreadcrumbs`) live as direct fields on `SentryOptions` with getter/setter pairs. Use this pattern for options that aren't tied to a specific feature namespace.
+
+## Configuration Layers
+
+Options can be set through multiple layers. When adding a new option, consider which layers apply:
+
+### 1. SentryOptions (always required)
+
+The core options class. Add the field (or nested class) with getter/setter here.
+
+**File:** `sentry/src/main/java/io/sentry/SentryOptions.java`
+
+**Tests:** `sentry/src/test/java/io/sentry/SentryOptionsTest.kt`
+- Test the default value
+- Test merge behavior (see layer 2)
+
+### 2. ExternalOptions (sentry.properties / environment variables)
+
+Allows setting options via `sentry.properties` file or system properties. Fields use nullable wrapper types (`@Nullable Boolean`, `@Nullable Double`) since unset means "don't override the default."
+
+**File:** `sentry/src/main/java/io/sentry/ExternalOptions.java`
+- Add `@Nullable` fields with getter/setter for each externally configurable option (e.g. `enableMetrics`, `logsSampleRate`)
+- Wire them in the static `from(PropertiesProvider)` method:
+  - Boolean: `propertiesProvider.getBooleanProperty("metrics.enabled")`
+  - Double: `propertiesProvider.getDoubleProperty("logs.sample-rate")`
+
+**File:** `sentry/src/main/java/io/sentry/SentryOptions.java` — `merge()` method
+- Add null-check blocks to apply each external option onto the namespaced options class:
+  ```java
+  if (options.isEnableMetrics() != null) {
+      getMetrics().setEnabled(options.isEnableMetrics());
+  }
+  if (options.getLogsSampleRate() != null) {
+      getLogs().setSampleRate(options.getLogsSampleRate());
+  }
+  ```
+
+**Tests:**
+- `sentry/src/test/java/io/sentry/ExternalOptionsTest.kt` — test true/false/null for booleans, valid values and null for doubles
+- `sentry/src/test/java/io/sentry/SentryOptionsTest.kt` — test merge applies values and test merge preserves defaults when unset
+
+### 3. Android Manifest Metadata (Android only)
+
+Allows setting options via `AndroidManifest.xml` `<meta-data>` tags.
+
+**File:** `sentry-android-core/src/main/java/io/sentry/android/core/ManifestMetadataReader.java`
+- Add a `static final String` constant for the key (e.g. `"io.sentry.metrics.enabled"`)
+- Read it in `applyMetadata()` using `readBool(metadata, logger, CONSTANT, defaultValue)`
+- Apply to the namespaced options, e.g. `options.getMetrics().setEnabled(...)`
+
+**Tests:** `sentry-android-core/src/test/java/io/sentry/android/core/ManifestMetadataReaderTest.kt`
+- Test default value preserved when not in manifest
+- Test explicit true
+- Test explicit false
+
+### 4. Spring Boot Properties (Spring Boot only)
+
+`SentryProperties` extends `SentryOptions`, so namespaced options (nested classes) are automatically available as Spring Boot properties without extra code. For example, `SentryOptions.Logs` is automatically mapped to `sentry.logs.enabled` in `application.properties`.
+
+No additional code is needed for namespaced options — Spring Boot auto-configuration handles this via property binding on the `SentryOptions` class hierarchy.
+
+**Tests:** `sentry-spring-boot*/src/test/kotlin/.../SentryAutoConfigurationTest.kt`
+- Add the property (e.g. `"sentry.logs.enabled=true"`) to the existing `resolves all properties` test
+- Assert the value is set on the resolved `SentryProperties` bean
+- There are three Spring Boot modules with separate test files: `sentry-spring-boot`, `sentry-spring-boot-jakarta`, `sentry-spring-boot-4`
+
+### 5. Reading Options at Runtime
+
+Features check their options at usage time. For namespaced features the check typically happens in the feature's API class (e.g. `LoggerApi`, `MetricsApi`):
+- Check `options.getLogs().isEnabled()` early and return if disabled
+- Apply sampling via `options.getLogs().getSampleRate()` if applicable
+- Apply `beforeSend` callback in `SentryClient` before sending
+
+When a feature has its own capture path (e.g. `captureLog`), the relevant classes are:
+- `ISentryClient` — add the capture method signature
+- `SentryClient` — implement capture, including `beforeSend` callback execution
+- `NoOpSentryClient` — add no-op stub
+
+## Checklist for Adding a New Namespaced Option
+
+1. `SentryOptions.java` — nested options class + getter/setter on `SentryOptions`
+2. `ExternalOptions.java` — `@Nullable` fields + wiring in `from()`
+3. `SentryOptions.java` `merge()` — apply external options to namespaced class
+4. `ManifestMetadataReader.java` — Android manifest support (if Android-relevant)
+5. `SentryAutoConfigurationTest.kt` — Spring Boot property binding tests (all three Spring Boot modules)
+6. Tests for all of the above (`SentryOptionsTest`, `ExternalOptionsTest`, `ManifestMetadataReaderTest`)
+7. Run `./gradlew apiDump` — the nested class and its methods appear in `sentry.api`