Merge branch 'main' into markushi/canvas-approach

Author: markushi

.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/new_module.mdc

@@ -0,0 +1,88 @@
+---
+description: Module Addition Rules for sentry-java
+alwaysApply: false
+---
+# Module Addition Rules for sentry-java
+
+## Overview
+
+This document outlines the complete process for adding a new module to the sentry-java repository. Follow these steps in order to ensure proper integration and release management.
+
+## Step-by-Step Process
+
+### 1. Create the Module Structure
+
+1. Create the new module, conforming to the existing naming conventions and build scripts
+
+2. Add the module to the include list in `settings.gradle.kts`
+
+If adding a `sentry-samples` module, also add it to the `ignoredProjects` list in the root `build.gradle.kts`:
+
+```kotlin
+ignoredProjects.addAll(
+    listOf(
+        // ... existing projects ...
+        "sentry-samples-{module-name}"
+    )
+)
+```
+
+3. If adding a JVM sample, add E2E (system) tests, following the structure we have in the existing JVM examples.
+   The test should then be added to `test/system-test-runner.py` and `.github/workflows/system-tests-backend.yml`.
+
+### 2. Create Module Documentation
+
+Create a `README.md` in the module directory with the following structure:
+
+```markdown
+# sentry-{module-name}
+
+This module provides an integration for [Technology/Framework Name].
+
+Please consult the documentation on how to install and use this integration in the Sentry Docs for [Android](https://docs.sentry.io/platforms/android/integrations/{module-name}/) or [Java](https://docs.sentry.io/platforms/java/tracing/instrumentation/{module-name}/).
+```
+
+The following tasks are required only when adding a module that isn't a sample.
+
+### 3. Update Main README.md
+
+Add the new module to the packages table in the main `README.md` with a placeholder link to the badge:
+
+```markdown
+| sentry-{module-name} | [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}) | |
+```
+
+Note that the badge will only work after the module is released to Maven Central.
+
+### 4. Add Documentation to docs.sentry.io
+
+Add the necessary documentation to [docs.sentry.io](https://docs.sentry.io):
+- For Java modules: Add to Java platform docs, usually in integrations section
+- For Android modules: Add to Android platform docs, usually in integrations section
+- Include installation instructions, configuration options, and usage examples
+
+### 5. Post release tasks
+
+Remind the user to perform the following tasks after the module is merged and released:
+
+1. Add the SDK to the Sentry release registry, following the instructions in the [sentry-release-registry README](https://github.com/getsentry/sentry-release-registry#adding-new-sdks)
+
+2. Add the module to `.craft.yml` in the `sdks` section:
+   ```yaml
+   sdks:
+     # ... existing modules ...
+     maven:io.sentry:sentry-{module-name}:
+   ```
+
+## Module Naming Conventions
+
+- Use kebab-case for module names: `sentry-{module-name}`
+- Follow existing patterns: `sentry-okhttp`, `sentry-apollo-4`, `sentry-spring-boot`
+- For version-specific modules, include the version: `sentry-apollo-3`, `sentry-apollo-4`
+
+## Important Notes
+
+1. **API Files**: Do not modify `.api` files manually. Run `./gradlew apiDump` to regenerate them
+2. **Backwards Compatibility**: Ensure new features are opt-in by default
+3. **Testing**: Write comprehensive tests for all new functionality
+4. **Documentation**: Always include proper documentation and examples

.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,65 @@
+---
+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
+
+- **`new_module`**: Use when adding a new integration or sample module
+
+### 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`
+   - new module/integration/sample → `new_module`
+   - Cache/offline/network → `offline`
+   - System test/e2e/sample → `e2e_tests`