Merge branch 'main' into feat/poc-continuous-profiling

Author: lbloder

.craft.yml

@@ -19,10 +19,13 @@ targets:
       maven:io.sentry:sentry:
       maven:io.sentry:sentry-spring:
       maven:io.sentry:sentry-spring-jakarta:
+#      maven:io.sentry:sentry-spring-7:
       maven:io.sentry:sentry-spring-boot:
       maven:io.sentry:sentry-spring-boot-jakarta:
       maven:io.sentry:sentry-spring-boot-starter:
       maven:io.sentry:sentry-spring-boot-starter-jakarta:
+#      maven:io.sentry:sentry-spring-boot-4:
+#      maven:io.sentry:sentry-spring-boot-4-starter:
       maven:io.sentry:sentry-servlet:
       maven:io.sentry:sentry-servlet-jakarta:
       maven:io.sentry:sentry-logback:
@@ -59,3 +62,4 @@ targets:
       maven:io.sentry:sentry-android-replay:
       maven:io.sentry:sentry-apollo-4:
       maven:io.sentry:sentry-reactor:
+      maven:io.sentry:sentry-ktor-client:

.cursor/rules/deduplication.mdc

@@ -0,0 +1,13 @@
+---
+alwaysApply: false
+description: Java SDK Event deduplication
+---
+
+# Java SDK Event deduplication
+
+To avoid sending the same error multiple times, there is deduplication logic in place in the SDK.
+Duplicate captures can happen due to multiple integrations capturing the exception as well as additional manual calls to `Sentry.captureException`.
+
+Deduplication is performed in `DuplicateEventDetectionEventProcessor` which returns `null` when it detects a duplicate event causing it to be dropped.
+
+The `enableDeduplication` option can be used to opt out of deduplication. It is enabled by default.

.cursor/rules/e2e_tests.mdc

@@ -0,0 +1,28 @@
+---
+alwaysApply: false
+description: Java SDK End to End Tests
+---
+
+# Java SDK End to End Tests (System Tests)
+
+The samples in the `sentry-samples` directory are used to run end to end tests against them.
+
+There is a python script (`system-test-runner.py`) that can be used to run one (using `--module SAMPLE_NAME`) or all (using `--all`) system tests.
+
+The script has an interactive mode (`-i`) which allows selection of test setups to execute, whether to run the tests or just prepare infrastructure for testing from IDE.
+
+The tests run a mock Sentry server via `system-test-sentry-server.py`. Any system under test will then have a DSN set that reflects this local mock server like `http://502f25099c204a2fbf4cb16edc5975d1@localhost:8000/0`.
+By using this local DSN, the system under test sends events to the local mock server.
+The tests can then use `TestHelper` to assert envelopes that were received by the mock server.
+`TestHelper` uses HTTP requests to retrieve the JSON payload of the received events and deserialize them back to objects for easier assertion.
+Tests can then assert events, transactions, logs etc. similar to how they would appear in `beforeSend` and similar callbacks.
+
+`TestHelper` has a lot of helper methods for asserting, e.g. by span name, log body etc.
+
+The end to end tests either expect the system under test to either be running on a server or call `java -jar` to execute a CLI system under test.
+
+For Spring Boot, we spin up the Spring Boot server. The tests then send requests to that server and assert what is sent to Sentry.
+
+End to end tests are also executed on CI using a matrix build, as defined in `.github/workflows/system-tests-backend.yml`.
+
+Some of the samples are tested in multiple ways, e.g. with OpenTelemetry Agent auto init turned on and off.

.cursor/rules/offline.mdc

@@ -1,5 +1,5 @@
 ---
-alwaysApply: true
+alwaysApply: false
 description: Java SDK Offline behaviour
 ---
 # Java SDK Offline behaviour

.cursor/rules/opentelemetry.mdc

@@ -0,0 +1,88 @@
+---
+alwaysApply: false
+description: Java SDK OpenTelemetry Integration
+---
+# Java SDK OpenTelemetry Integration
+
+## Overview
+
+The Sentry Java SDK provides comprehensive OpenTelemetry integration through multiple modules:
+
+- `sentry-opentelemetry-core`: Core OpenTelemetry integration functionality
+- `sentry-opentelemetry-agent`: Java Agent-based integration for automatic instrumentation
+- `sentry-opentelemetry-agentless`: Manual instrumentation without Java agent
+- `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.
+
+## Advantages over using Sentry without OpenTelemetry
+
+- Support for more libraries and frameworks
+    - See https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation for a list of supported libraries and frameworks
+- More automated Performance instrumentation (spans) created
+    - Using `sentry-opentelemetry-agent` offers most support
+    - Using `sentry-opentelemetry-agentless-spring` for Spring Boot also has a lot of supported libraries, altough fewer than the agent does
+    - Note that `sentry-opentelemetry-agentless` will not have any OpenTelemetry auto instrumentation
+- Sentry also relies on OpenTelemetry `Context` propagation to propagate Sentry `Scopes`, ensuring e.g. that execution flow for a request shares data and does not leak data into other requests.
+- OpenTelemetry also offers better support for distributed tracing since more libraries are supported for attaching tracing information to outgoing requests and picking up incoming tracing information.
+
+## Key Components
+
+### Agent vs Agentless
+
+**Java Agent-based integration**:
+- Automatic instrumentation via Java agent
+- Can be added to any JAR when starting, no extra dependencies or code changes required. Just add the agent when running the application, e.g. `SENTRY_PROPERTIES_FILE=sentry.properties JAVA_TOOL_OPTIONS="-javaagent:sentry-opentelemetry-agent.jar" java -jar your-application.jar`.
+- Uses OpenTelemetry Java agent with Sentry extensions
+- Uses bytecode manipulation
+
+**Agentless-Spring integration**:
+- Automatic instrumentation setup via Spring Boot
+- Dependency needs to be added to the project.
+
+**Agentless integration**:
+- Manual instrumentation setup
+- Dependency needs to be added to the project.
+
+**Manual Integration**:
+While it's possible to manually wire up all the required classes to make Sentry and OpenTelemetry work together, we do not recommend this.
+It is instead preferrable to use `SentryAutoConfigurationCustomizerProvider` so the Sentry SDK has a place to manage required classes and update it when changes are needed.
+This way customers receive the updated config automatically as oppposed to having to update manually, wire in new classes, remove old ones etc.
+
+### Integration Architecture
+
+Sentry will try to locate certain classes that come with the Sentry OpenTelemetry integration to:
+- Determine whether any Sentry OpenTelemetry integration is present
+- Determine which mode to use and in turn which Sentry auto instrumentation to suppress
+
+Reflection is used to search for `io.sentry.opentelemetry.OtelContextScopesStorage` and use it instead of `DefaultScopesStorage` when a Sentry OpenTelemetry integration is present at runtime. `IScopesStorage` is used to store Sentry `Scopes` instances. `DefaultScopesStorage` will use a thread local variable to store the current threads' `Scopes` whereas `OtelContextScopesStorage` makes use of OpenTelemetry SDKs `Context`. Sentry OpenTelemetry integrations configure OpenTelemetry to use `SentryOtelThreadLocalStorage` to customize restoring of the previous `Context`.
+
+OpenTelemetry SDK makes use of `io.opentelemetry.context.Scope` in `try-with-resources` statements that call `close` when a code block is finished. Without customization, it would refuse to restore the previous `Context` onto the `ThreadLocal` if the current state of the `ThreadLocal` isn't the same as the one this scope was created for. Sentry changes this behaviour in `SentryScopeImpl` to restore the previous `Context` onto the `ThreadLocal` even if an inner `io.opentelemetry.context.Scope` wasn't properly cleaned up. Our thinking here is to prefer returning to a clean state as opposed to propagating the problem. The unclean state could happen, if `io.opentelemetry.context.Scope` isn't closed, e.g. when forgetting to put it in a `try-with-resources` statement and not calling `close` (e.g. not putting it in a `finally` block in that case).
+
+`SentryContextStorageProvider` looks for any other `ContextStorageProvider` and forwards to that to not override any customized `ContextStorage`. If no other provider is found, `SentryOtelThreadLocalStorage` is used.
+
+`SpanFactoryFactory` is used to configure Sentry to use `io.sentry.opentelemetry.OtelSpanFactory` if the class is present at runtime. Reflection is used to search for it. If the class is not available, we fall back to `DefaultSpanFactory`.
+
+`DefaultSpanFactory` creates a `SentryTracer` instance when creating a transaction and spans are then created directly on the transaction via `startChild`.
+`OtelSpanFactory` instead creates an OpenTelemetry span and wraps it using `OtelTransactionSpanForwarder` to simulate a transaction. The `startChild` invocations on `OtelTransactionSpanForwarder` go through `OtelSpanFactory` again to create the child span.
+
+## Configuration
+
+We use `SentryAutoConfigurationCustomizerProvider` to configure OpenTelemetry for use with Sentry and register required classes, hooks etc.
+
+## Span Processing
+
+Both Sentry and OpenTelemetry API can be used to create spans. When using Sentry API, `OtelSpanFactory` is used to indirectly create a OpenTelemetry span.
+Regardless of API used, when an OpenTelemetry span is created, it goes through `SentrySampler` for sampling and `OtelSentrySpanProcessor` for `Scopes` forking and ensuring the trace is continued.
+When Sentry API is used, sampling is performed in `Scopes.createTransaction` before forwarding the call to `OtelSpanFactory`. The sampling decision and other sampling details are forwarded to `SentrySampler` and `OtelSentrySpanProcessor`.
+
+When a span is finished, regardless of whether Sentry or OpenTelemetry API is used, it goes through `OtelSentrySpanProcessor` to set the end date and then through `BatchSpanProcessor` which will batch spans and then forward them to `SentrySpanExporter`.
+
+`SentrySpanExporter` collects spans, then structures them to create a transaction for the local root span and attaches child spans to form a span tree.
+Some OpenTelemetry attributes are transformed into their corresponding Sentry data structure or format.
+
+After creating the transaction with child spans `SentrySpanExporter` uses Sentry API to send the transaction to Sentry. This API call however forces the use of `DefaultSpanFactory` in order to create the required Sentry classes for sending and also to not create an infinite loop where any span created will cause a new span to be created recursively.
+
+## 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.

.cursor/rules/overview_dev.mdc

@@ -0,0 +1,62 @@
+---
+alwaysApply: true
+description: Sentry Java SDK - Development Rules Overview
+---
+
+# Sentry Java SDK Development Rules
+
+## Always Applied Rules
+
+These rules are automatically included in every conversation:
+- **coding.mdc**: General contributing guidelines, build commands, and workflow rules
+
+## Domain-Specific Rules (Fetch Only When Needed)
+
+Use the `fetch_rules` tool to include these rules when working on specific areas:
+
+### Core SDK Functionality
+- **`scopes`**: Use when working with:
+  - Hub/Scope management, forking, or lifecycle
+  - `Sentry.getCurrentScopes()`, `pushScope()`, `withScope()` 
+  - `ScopeType` (GLOBAL, ISOLATION, CURRENT)
+  - Thread-local storage, scope bleeding issues
+  - Migration from Hub API (v7 → v8)
+
+- **`deduplication`**: Use when working with:
+  - Duplicate event detection/prevention
+  - `DuplicateEventDetectionEventProcessor`
+  - `enableDeduplication` option
+
+- **`offline`**: Use when working with:
+  - Caching, envelope storage/retrieval
+  - Network failure handling, retry logic
+  - `AsyncHttpTransport`, `EnvelopeCache`
+  - Rate limiting, cache rotation
+  - Android vs JVM caching differences
+
+### Integration & Infrastructure
+- **`opentelemetry`**: Use when working with:
+  - OpenTelemetry modules (`sentry-opentelemetry-*`)
+  - Agent vs agentless configurations
+  - Span processing, sampling, context propagation
+  - `OtelSpanFactory`, `SentrySpanExporter`
+  - Tracing, distributed tracing
+
+### Testing
+- **`e2e_tests`**: Use when working with:
+  - System tests, sample applications
+  - `system-test-runner.py`, mock Sentry server
+  - End-to-end test infrastructure
+  - CI system test workflows
+
+## Usage Guidelines
+
+1. **Start minimal**: Only include `coding.mdc` (auto-applied) for general tasks
+2. **Fetch on-demand**: Use `fetch_rules ["rule_name"]` when you identify specific domain work
+3. **Multiple rules**: Fetch multiple rules if task spans domains (e.g., `["scopes", "opentelemetry"]` for tracing scope issues)
+4. **Context clues**: Look for these keywords in requests to determine relevant rules:
+   - Scope/Hub/forking → `scopes`
+   - Duplicate/dedup → `deduplication` 
+   - OpenTelemetry/tracing/spans → `opentelemetry`
+   - Cache/offline/network → `offline`
+   - System test/e2e/sample → `e2e_tests`

.cursor/rules/scopes.mdc

@@ -0,0 +1,112 @@
+---
+alwaysApply: false
+description: Java SDK Hubs and Scopes
+---
+# Java SDK Hubs and Scopes
+
+## `Scopes`
+
+`Scopes` implements `IScopes` and manages three `Scope` instances, `global`, `isolation` and `current` scope.
+For some data, all three `Scope` instances are combined, for others, a certain one is used exclusively and for some we look at each scope in a certain order and use the data of the first scope that has the data set. This logic is contained in `CombinedScopeView`.
+Data itself is stored on `Scope` instances.
+`Scopes` also has a `parent` field, linking the `Scopes` it was forked off of and a `creator` String, explaining why it was forked.
+
+## `Hub`
+
+Up until major version 7 of the Java SDK the `IHub` interface was a central part of the SDK.
+In major version 8 we replaced the `IHub` interface with `IScopes`. `IHub` has been deprecated.
+While there is some bridging code in place to allow for easier migration, we are planning to remove it in an upcoming major.
+
+## Scope Types
+
+We have introduced some new Scope types in the SDK, allowing for better control over what data is attached where.
+Previously there was a stack of scopes that was pushed and popped.
+Instead we now fork scopes for a given lifecycle and then restore the previous scopes.
+Since Hub is gone, it is also never cloned anymore.
+Separation of data now happens through the different scope types while making it easier to manipulate exactly what you need without having to attach data at the right time to have it apply where wanted.
+
+### Global Scope
+
+Global scope is attached to all events created by the SDK.
+It can also be modified before Sentry.init has been called.
+It can be manipulated using `Sentry.configureScope(ScopeType.GLOBAL, (scope) -> { ... })`.
+
+Global scope can be retrieved from `Scopes` via `getGlobalScope`. It can also be retrieved directly via `Sentry.getGlobalScope`.
+
+### Isolation Scope
+
+Isolation scope can be used e.g. to attach data to all events that come up while handling an incoming request.
+It can also be used for other isolation purposes.
+It can be manipulated using `Sentry.configureScope(ScopeType.ISOLATION, (scope) -> { ... })`.
+The SDK automatically forks isolation scope in certain cases like incoming requests, CRON jobs, Spring `@Async` and more.
+
+Isolation scope can be retrieved from `Scopes` via `getIsolationScope`.
+
+### Current scope
+
+Current scope is forked often and data added to it is only added to events that are created while this scope is active.
+Data is also passed on to newly forked child scopes but not to parents.
+
+Current scope can be retrieved from `Scopes` via `getScope`.
+
+## Storage of `Scopes`
+
+`Scopes` are stored in a `ThreadLocal` by default (NOTE: this is different for OpenTelemetry, see opentelemetry.mdc).
+This happens through `Sentry.scopesStorage` and `DefaultScopesStorage`.
+
+The lifetime of `Scopes` in the thread local is managed by `ISentryLifecycleToken`.
+When the scopes are forked, they are stored into the `ThreadLocal` and a `ISentryLifecycleToken` is returned.
+When the `Scopes` are no longer needed, e.g. because a request is finished, `ISentryLifecycleToken.close` can be called to restore the previous state of the `ThreadLocal`.
+
+## Old versions of the Java SDK
+
+There were several implementations of the `IHub` interface:
+- `Hub` managed a stack of `Scope` instances, which were pushed and popped.
+- A `Hub` could be cloned, meaning there could be multiple stacks of scopes active, e.g. for two separate requests being handled in a server application.
+
+### Migrating to major version 8 of the SDK
+
+`IHub` has been replaced by `IScopes`
+`HubAdapter` has been replaced by `ScopesAdapter`
+`Hub.clone` should be replaced by using `pushScope` or `pushIsolationScope`
+`Sentry.getCurrentHub` has been replaced by `Sentry.getCurrentScopes`
+`Sentry.popScope` has been deprecated. Instead `close` should be called on the `ISentryLifecycleToken` returned e.g. by `pushScope`. This can also be done in a `try-with-resource` block.
+
+## `globalHubMode`
+The SDK has a `globalHubMode` option which affects forking behaviour of the SDK.
+
+Android has `globalHubMode` enabled by default.
+For JVM Desktop applications, `globalHubMode` can be used.
+For JVM Backend applications (servers) we discourage enabling `globalHubMode` since it will cause scopes to bleed into each other. This can e.g. mean that state from request A leaks into request B and events sent to Sentry contain a mix of both request A and B potentially rendering the data useless.
+
+### Enabled
+
+If `globalHubMode` is enabled, the SDK avoids forking scopes.
+
+This means, retrieving current scopes on a thread where specific scopes do not exist yet for the thread, the root scopes are not forked but returned directly.
+The SDK also doesn't fork scopes when `Sentry.pushScope`, `Sentry.pushIsolation`, `Sentry.withScope` or `Sentry.withIsolationScope` are executed.
+
+The suppression of forking via `globalHubMode` only applies when using `Sentry` static API or `ScopesAdapter`.
+In case the `Scopes` instance is accessed directly, forking will happen as if `globalHubMode` is disabled.
+However, while it's possible to use `Sentry.setCurrentScopes` it does not have any effect due to `Sentry.getCurrentScopes` directly returning `rootScopes` if `globalHubMode` is enabled.
+This means the forked scopes have to be managed manually, e.g. by keeping a reference and accessing Sentry API via the reference instead of using static API.
+
+`ScopesAdapter` makes use of the static `Sentry` API internally. It allows us to access the correct scopes for the current context without passing it along explicitly. It also makes testing easier.
+
+### Disabled
+
+If `globalHubMode` is disabled, the SDK forks scopes freely, e.g. when:
+- `Sentry.getCurrentScopes()` is executed on a Thread where no specific scopes for that thread have been stored yet. In this case the SDK will fork `rootScopes` (stored in a `Sentry` static property).
+- `withScope` or `withIsolationScope` are executed
+- `pushScope` or `pushIsolationScope` are executed
+
+## `defaultScopeType`
+
+The `defaultScopeType` controls which `Scope` instance is being used for writing to and reading from as a default value.
+When using API like `Sentry.setTag` the SDK adds that tag to the default `Scope`.
+
+This also ensures, customers who migrate to the latest SDK version and already have `Sentry.configureScope` invocations in place, will now write to the default `Scope` instance that was chosen.
+
+The default value for `defaultScopeType` is `ISOLATION` scope for JVM and `CURRENT` scope for Android.
+
+Which fields are written/read from/to `defaultScopeType` is controlled in `CombinedScopeView`.

.fossa.yml

@@ -0,0 +1,4 @@
+version: 3
+targets:
+  exclude:
+    - type: setuptools