Update v9 branch

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

@@ -74,10 +74,10 @@ Derive the branch name from the changes being made. Use `feat/`, `fix/`, `ref/`,
 ## Step 2: Format Code and Regenerate API Files
 
 ```bash
-./gradlew spotlessApply updateKotlinAbi
+make format api
 ```
 
-This is **required** before every PR in this repo. It formats all Java/Kotlin code via Spotless and regenerates the `.api` binary compatibility files.
+This is **required** before every PR in this repo. It formats all Java/Kotlin code via Spotless, including the separate builds the root `spotlessApply` doesn't reach, and regenerates the `.api` binary compatibility files.
 
 If the command fails, diagnose and fix the issue before continuing.
 

.cursor/BUGBOT.md

@@ -13,15 +13,26 @@ rule file in [`.cursor/rules/`](rules) for the area the diff touches (`api`, `op
 - While we don't want to crash or hang the host application, we also don't want to leave the host
   application in a bad or unrecoverable state. Therefore catch the narrowest type the guarded code
   can throw.
-- Existing broad catches like `catch (Throwable)` are legacy, not precedent. Where a broad catch is
-  genuinely unavoidable (an entry point running user code or third-party callbacks), it must call
-  `ExceptionUtils.rethrowIfFatal(t)` first and a code comment must say why the broad catch is
-  needed.
+- Flag any new broad catch (`Throwable`, `Error`, `Exception`, `RuntimeException`) outside a
+  boundary where we can't know what the other side throws, e.g. public API entry points like
+  `captureException`, or Android framework calls that cross into another process
+  (`ContentResolver`, system services). Existing broad catches are legacy, not precedent. See the
+  Exception Handling section in `AGENTS.md`.
+- A broad catch at a boundary must call `ExceptionUtils.rethrowIfFatal(t)` first and requires a
+  code comment saying why the catch is broad and what happens on failure (event dropped, feature
+  disabled, ...).
+- A broad catch that wraps user code requires documentation, both in code and in sentry-docs,
+  explaining how the user is expected to discover that the code they wrote isn't working.
+  sentry-docs is a separate repository, so ask the author to link the docs PR.
 - Code probing for an optional `compileOnly` dependency must catch the specific `LinkageError`
-  subclass (`NoClassDefFoundError`, `NoSuchMethodError`, ...) only.
+  subclass (`NoClassDefFoundError`, `NoSuchMethodError`, ...). Flag a probe guarded only by a broad
+  catch with `rethrowIfFatal`: it rethrows every `LinkageError`, crashing the host app when the
+  dependency is missing.
+- Logging is not handling: `options.getLogger()` is silent unless `debug` is enabled. When a catch
+  only logs, ask the author what the customer sees when it fires.
 - The SDK must never `captureException`/`captureMessage` for its own failures or for exceptions
-  thrown inside user callbacks (`beforeSend`, `beforeBreadcrumb`, `tracesSampler`, ...). Log via
-  `options.getLogger()` instead — capturing here loops. See
+  thrown inside user callbacks (`beforeSend`, `beforeBreadcrumb`, `tracesSampler`, ...) — capturing
+  here loops. See
   [Never capture your own exceptions](https://develop.sentry.dev/sdk/getting-started/principles/#never-capture-your-own-exceptions).
 - Flag `System.out`/`System.err`, `printStackTrace()`, and `android.util.Log` in SDK source; use
   `options.getLogger().log(...)`.

.cursor/rules/e2e_tests.mdc

@@ -83,8 +83,9 @@ it. Gradle runs the two in parallel.
   customizes, and that the OpenTelemetry starter instruments, so it adds or replaces trace headers
   on the requests a test sends. Build one outside the context.
 - Sentry exports OpenTelemetry spans in batches every 5 seconds. In-process, flush the tracer
-  provider from the server's hook. With the agent this isn't possible, so each test waits for a
-  batch and negative checks wait at least 6 seconds.
+  provider from the server's hook. With the agent this isn't possible, so set
+  `OTEL_BSP_SCHEDULE_DELAY` on the app to shorten the batch delay, and make negative checks wait
+  well past it.
 - Sentry is global, so a second live Spring context in an OpenTelemetry suite takes it over. Keep
   one live context per JVM (`@DirtiesContext` when a test needs its own).
 - The async profiler rejects a traces path with a `.` anywhere in its absolute form. Put the path

.cursor/rules/new_module.mdc

@@ -31,16 +31,11 @@ the release that first ships it. All of the following have to be merged **before
 
 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}"
-    )
-)
-```
+If adding a sample, add an `include("…")` line for it to `sentry-samples/settings.gradle.kts`
+instead, and apply `id("io.sentry.spotless")` and `id("io.sentry.jdk-target")` in its `plugins`
+block. The samples are a separate Gradle build that includes the SDK build, so a sample depends on
+`"io.sentry:sentry-{module-name}:$sentryVersion"` (with `val sentryVersion =
+libs.versions.sentry.get()`), and Gradle substitutes the SDK's project for it.
 
 3. Add a `SENTRY_{MODULE}_SDK_NAME` constant to the `Config.Sentry` block in
    `buildSrc/src/main/java/Config.kt`:

.github/dependabot.yml

@@ -7,7 +7,12 @@ registries:
     password: dummy # Required by dependabot
 updates:
   - package-ecosystem: "gradle"
-    directory: "/"
+    # The root build doesn't include the separate sample and test builds.
+    directories:
+      - "/"
+      - "/sentry-samples/sentry-samples-android"
+      - "/sentry-android-integration-tests"
+      - "/sentry-samples"
     registries:
       - gradle-plugin-portal
     schedule:

.github/workflows/agp-matrix.yml

@@ -24,13 +24,15 @@ jobs:
     env:
       VERSION_AGP: ${{ matrix.agp }}
       APPLY_SENTRY_INTEGRATIONS: ${{ matrix.integrations }}
+      # Upload replay snapshots from one cell only. Forks don't have access to the upload secret.
+      UPLOAD_REPLAY_SNAPSHOTS: ${{ matrix.agp == '9.4.0' && matrix.integrations && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
 
     steps:
       - name: Checkout Repo
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup Java Version
-        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
         with:
           distribution: 'temurin'
           java-version: '21'
@@ -51,20 +53,21 @@ jobs:
           path: |
             ~/.android/avd/*
             ~/.android/adb*
-          key: avd-api-30-x86_64-aosp_atd
+          key: avd-api-30-x86_64-google_apis
 
       - name: Create AVD and generate snapshot for caching
         if: steps.avd-cache.outputs.cache-hit != 'true'
         uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # pin@v2
         with:
           api-level: 30
-          target: aosp_atd
-          channel: canary # Necessary for ATDs
+          # Not an ATD image: PixelCopy returns no data on ATDs, which the replay tests need
+          target: google_apis
+          channel: canary
           arch: x86_64
           force-avd-creation: false
           disable-animations: true
           disable-spellchecker: true
-          emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
+          emulator-options: -memory 4096 -no-window -gpu auto -noaudio -no-boot-anim -camera-back none
           disk-size: 4096M
           script: echo "Generated AVD snapshot for caching."
 
@@ -77,15 +80,28 @@ jobs:
         uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # pin@v2
         with:
           api-level: 30
-          target: aosp_atd
-          channel: canary # Necessary for ATDs
+          # Not an ATD image: PixelCopy returns no data on ATDs, which the replay tests need
+          target: google_apis
+          channel: canary
           arch: x86_64
           force-avd-creation: false
           disable-animations: true
           disable-spellchecker: true
-          emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
+          emulator-options: -memory 4096 -no-snapshot-save -no-window -gpu auto -noaudio -no-boot-anim -camera-back none
           disk-size: 4096M
-          script: ./gradlew sentry-android-integration-tests:sentry-uitest-android:connectedReleaseAndroidTest -Denvironment=github --daemon
+          script: ./scripts/test-ui-android.sh replay-snapshots
+
+      - name: Install Sentry CLI
+        if: ${{ !cancelled() && env.UPLOAD_REPLAY_SNAPSHOTS == 'true' }}
+        uses: getsentry/action-setup-cli@70d7e587b84c2e78cf4d37cd33d7b74fb3729c1b # v1
+
+      - name: Upload Replay Snapshots to Sentry
+        if: ${{ !cancelled() && env.UPLOAD_REPLAY_SNAPSHOTS == 'true' && hashFiles('replay-snapshots/*.png') != '' }}
+        run: sentry-cli snapshots upload ./replay-snapshots --app-id sentry-android-replay
+        env:
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+          SENTRY_ORG: sentry-sdks
+          SENTRY_PROJECT: sentry-android
 
       - name: Upload test results
         if: always()
@@ -96,6 +112,7 @@ jobs:
             **/build/reports/*
             **/build/outputs/*/connected/*
             **/build/outputs/mapping/release/*
+            replay-snapshots/
 
       - name: Test Report
         uses: phoenix-actions/test-reporting@7317eea6e13c47348dd0bb318669485157c518d6 # pin@v16

.github/workflows/build.yml

@@ -22,7 +22,7 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup Java Version
-        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
         with:
           distribution: 'temurin'
           java-version: '21'

.github/workflows/changes-in-high-risk-code.yml

@@ -39,11 +39,79 @@ jobs:
           high_risk_code: ${{ needs.files-changed.outputs.high_risk_code_files }}
         with:
           script: |
-            const highRiskFiles = process.env.high_risk_code;
-            const fileList = highRiskFiles.split(',').map(file => `- [ ] ${file}`).join('\n');
-            github.rest.issues.createComment({
+            const highRiskFiles = process.env.high_risk_code
+              .split(',')
+              .map(file => file.trim())
+              .filter(Boolean);
+
+            const marker = '🚨 Detected changes in high risk code 🚨';
+            const intro = `### ${marker} \n High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:`;
+
+            const buildBody = (files, checkedFiles = new Set()) => {
+              const fileList = files
+                .map(file => `- [${checkedFiles.has(file) ? 'x' : ' '}] ${file}`)
+                .join('\n');
+              return `${intro}\n${fileList}`;
+            };
+
+            const parseCheckedFiles = (commentBody = '') => {
+              const checked = new Set();
+              for (const match of commentBody.matchAll(/^[ \t]*- \[x\] (.+)$/gim)) {
+                checked.add(match[1].trim());
+              }
+              return checked;
+            };
+
+            const parseListedFiles = (commentBody = '') => {
+              const listed = [];
+              for (const match of commentBody.matchAll(/^[ \t]*- \[[ xX]\] (.+)$/gim)) {
+                listed.push(match[1].trim());
+              }
+              return listed;
+            };
+
+            const sameFileSet = (a, b) => {
+              if (a.length !== b.length) return false;
+              const left = [...a].sort().join('\n');
+              const right = [...b].sort().join('\n');
+              return left === right;
+            };
+
+            // Get existing comments (paginate so older comments are not missed)
+            const comments = await github.paginate(github.rest.issues.listComments, {
               issue_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: `### 🚨 Detected changes in high risk code 🚨 \n High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:\n ${fileList}`
-            })
+              per_page: 100
+            });
+
+            const existingComment = comments.find(comment =>
+              comment.body?.includes(marker)
+            );
+
+            // Keep one warning comment. Only rewrite when the file set changes,
+            // and preserve reviewer checkbox state for files that remain.
+            if (existingComment) {
+              const previousFiles = parseListedFiles(existingComment.body);
+              if (sameFileSet(previousFiles, highRiskFiles)) {
+                return;
+              }
+
+              const body = buildBody(
+                highRiskFiles,
+                parseCheckedFiles(existingComment.body)
+              );
+              await github.rest.issues.updateComment({
+                comment_id: existingComment.id,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: buildBody(highRiskFiles)
+              });
+            }

.github/workflows/codeql-analysis.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup Java Version
-        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
         with:
           distribution: 'temurin'
           java-version: '21'
@@ -29,7 +29,7 @@ jobs:
         uses: gradle/actions/setup-gradle@8da46b539cd8fe6ab27ca75128919a18d757604c # v6.4.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # pin@v2
+        uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # pin@v2
         with:
           languages: 'java'
 
@@ -38,4 +38,4 @@ jobs:
           ./gradlew buildForCodeQL --no-build-cache
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # pin@v2
+        uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # pin@v2

.github/workflows/enforce-license-compliance.yml

@@ -14,7 +14,7 @@ jobs:
         uses: gradle/actions/setup-gradle@8da46b539cd8fe6ab27ca75128919a18d757604c # v6.4.1
 
       - name: Set up Java
-        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
         with:
           distribution: 'temurin'
           java-version: '21'

.github/workflows/format-code.yml

@@ -11,7 +11,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: set up JDK 17
-        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
         with:
           distribution: 'temurin'
           java-version: '21'
@@ -20,7 +20,7 @@ jobs:
         uses: gradle/actions/setup-gradle@8da46b539cd8fe6ab27ca75128919a18d757604c # v6.4.1
 
       - name: Format with spotlessApply
-        run: ./gradlew spotlessApply
+        run: make format
 
       # actions/checkout fetches only a single commit in a detached HEAD state. Therefore
       # we need to pass the current branch, otherwise we can't commit the changes.

.github/workflows/generate-javadocs.yml

@@ -12,7 +12,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: set up JDK 17
-        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
         with:
           distribution: 'temurin'
           java-version: '21'

.github/workflows/integration-tests-macrobenchmark.yml

@@ -1,5 +1,5 @@
 name: 'Integration Tests - Macrobenchmark'
-# Runs the sentry-uitest-android-macrobenchmark cold-start benchmark on a Sauce Labs real
+# Runs the sentry-samples-android macrobenchmark cold-start benchmark on a Sauce Labs real
 # device and recovers timeToInitialDisplay from the device log.
 #
 on:
@@ -23,7 +23,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: 'Set up Java: 17'
-        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
         with:
           distribution: 'temurin'
           java-version: '21'
@@ -33,7 +33,7 @@ jobs:
 
       - name: Assemble target app and Macrobenchmark apk
         if: env.SAUCE_USERNAME != null
-        run: ./gradlew :sentry-samples:sentry-samples-android:assembleRelease :sentry-android-integration-tests:sentry-uitest-android-macrobenchmark:assembleBenchmark
+        run: ./gradlew -p sentry-samples/sentry-samples-android :assembleRelease :macrobenchmark:assembleBenchmark
 
       - name: Run Macrobenchmark in SauceLab
         uses: saucelabs/saucectl-run-action@283660aa934c02723c497efa151d582a3acc5801 # pin@v3

.github/workflows/integration-tests-size.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup Java Version
-        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
         with:
           distribution: "temurin"
           java-version: "21"
@@ -29,6 +29,6 @@ jobs:
         uses: gradle/actions/setup-gradle@8da46b539cd8fe6ab27ca75128919a18d757604c # v6.4.1
 
       - name: Size Analysis
-        run: ./gradlew :sentry-android-integration-tests:test-app-size:bundleRelease
+        run: ./gradlew -p sentry-android-integration-tests :test-app-size:bundleRelease
         env:
           SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}