Merge branch 'main' into feat/strict-trace-continuation

Author: adinauer

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

@@ -35,6 +35,8 @@ Derive the branch name from the changes being made. Use `feat/`, `fix/`, `ref/`,
 
 **For stacked PRs:** For the first PR in a new stack, first create and push the collection branch (see `.cursor/rules/pr.mdc` § "Creating the Collection Branch"), then branch the PR off it. For subsequent PRs, branch off the previous stack branch. Use the naming conventions from `.cursor/rules/pr.mdc` § "Branch Naming".
 
+**CRITICAL: Never merge, fast-forward, or push commits into the collection branch.** It stays at its initial position until the user merges stack PRs through GitHub. Updating it will auto-merge and destroy the entire PR stack.
+
 ## Step 2: Format Code and Regenerate API Files
 
 ```bash
@@ -111,14 +113,21 @@ Fill in each section based on the changes being PR'd. Check any checklist items
 - Pass `--base <previous-stack-branch>` so the PR targets the previous branch (first PR in a stack targets the collection branch).
 - Use the stacked PR title format: `<type>(<scope>): [<Topic> <N>] <Subject>` (see `.cursor/rules/pr.mdc` § "PR Title Naming").
 - Include the stack list at the top of the PR body, before the `## :scroll: Description` section (see `.cursor/rules/pr.mdc` § "Stack List in PR Description" for the format).
+- Add a merge method reminder at the very end of the PR body (see `.cursor/rules/pr.mdc` § "Stack List in PR Description" for the exact text). This only applies to stack PRs, not the collection branch PR.
 
 Then continue to Step 5.5 (stacked PRs only) or Step 6.
 
 ## Step 5.5: Update Stack List on All PRs (stacked PRs only)
 
 Skip this step for standalone PRs.
 
-After creating the PR, update the PR description on **every other PR in the stack** so all PRs have the same up-to-date stack list. Follow the format and commands in `.cursor/rules/pr.mdc` § "Stack List in PR Description".
+After creating the PR, update the PR description on **every other PR in the stack — including the collection branch PR** — so all PRs have the same up-to-date stack list. Follow the format and commands in `.cursor/rules/pr.mdc` § "Stack List in PR Description".
+
+**Important:** When updating PR bodies, never use shell redirects (`>`, `>>`) or pipes (`|`) or compound commands (`&&`). These create compound shell expressions that won't match permission patterns. Instead:
+- Use `gh pr view <NUMBER> --json body --jq '.body'` to get the body (output returned directly)
+- Use the `Write` tool to save it to a temp file
+- Use the `Edit` tool to modify the temp file
+- Use `gh pr edit <NUMBER> --body-file /tmp/pr-body.md` to update
 
 ## Step 6: Update Changelog
 
@@ -170,8 +179,6 @@ git push
 
 If no changelog entry is needed, add `#skip-changelog` to the PR description to disable the changelog CI check:
 
-```bash
-gh pr view <PR_NUMBER> --json body --jq '.body' > /tmp/pr-body.md
-printf '\n#skip-changelog\n' >> /tmp/pr-body.md
-gh pr edit <PR_NUMBER> --body-file /tmp/pr-body.md
-```
+1. Get the current body: `gh pr view <PR_NUMBER> --json body --jq '.body'`
+2. Use the `Write` tool to save the output to `/tmp/pr-body.md`, appending `\n#skip-changelog\n` at the end
+3. Update: `gh pr edit <PR_NUMBER> --body-file /tmp/pr-body.md`

.cursor/rules/continuous_profiling_jvm.mdc

@@ -0,0 +1,174 @@
+---
+alwaysApply: false
+description: JVM Continuous Profiling (sentry-async-profiler)
+---
+# JVM Continuous Profiling
+
+Use this rule when working on JVM continuous profiling in `sentry-async-profiler` and the related core profiling abstractions in `sentry`.
+
+This area is suitable for LLM work, but do not rely on this rule alone for behavior changes. Always read the implementation and nearby tests first, especially for sampling, lifecycle, rate limiting, and file cleanup behavior.
+
+## Module Structure
+
+- **`sentry-async-profiler`**: standalone module containing the async-profiler integration
+  - Uses Java `ServiceLoader` discovery
+  - No direct dependency from core `sentry` module
+  - Enabled by adding the module as a dependency
+
+- **`sentry` core abstractions**:
+  - `IContinuousProfiler`: profiler lifecycle interface
+  - `ProfileChunk`: profile chunk payload sent to Sentry
+  - `IProfileConverter`: converts JVM JFR files into `SentryProfile`
+  - `ProfileLifecycle`: controls MANUAL vs TRACE lifecycle
+  - `ProfilingServiceLoader`: loads profiler and converter implementations via `ServiceLoader`
+
+## Key Classes
+
+### `JavaContinuousProfiler` (`sentry-async-profiler`)
+- Wraps the native async-profiler library
+- Writes JFR files to `profilingTracesDirPath`
+- Rotates chunks periodically via `MAX_CHUNK_DURATION_MILLIS` (currently 10s)
+- Implements `RateLimiter.IRateLimitObserver`
+- Maintains `rootSpanCounter` for TRACE lifecycle
+- Keeps a session-level `profilerId` across chunks until the profiling session ends
+- `getChunkId()` currently returns `SentryId.EMPTY_ID`, but emitted `ProfileChunk`s get a fresh chunk id when built in `stop(...)`
+
+### `ProfileChunk`
+- Carries `profilerId`, `chunkId`, timestamp, platform, measurements, and a JFR file reference
+- Built via `ProfileChunk.Builder`
+- For JVM, the JFR file is converted later during envelope item creation, not inside `JavaContinuousProfiler`
+
+### `ProfileLifecycle`
+- `MANUAL`: explicit `Sentry.startProfiler()` / `Sentry.stopProfiler()`
+- `TRACE`: profiler lifecycle follows active sampled root spans
+
+## Configuration
+
+Continuous profiling is **not** controlled by `profilesSampleRate`.
+
+Key options:
+- **`profileSessionSampleRate`**: session-level sample rate for continuous profiling
+- **`profileLifecycle`**: `ProfileLifecycle.MANUAL` (default) or `ProfileLifecycle.TRACE`
+- **`cacheDirPath`**: base SDK cache directory; profiling traces are written under the derived `profilingTracesDirPath`
+- **`profilingTracesHz`**: sampling frequency in Hz (default: 101)
+
+Continuous profiling is enabled when:
+- `profilesSampleRate == null`
+- `profilesSampler == null`
+- `profileSessionSampleRate != null && profileSessionSampleRate > 0`
+
+Example:
+
+```java
+options.setProfileSessionSampleRate(1.0);
+options.setCacheDirPath("/tmp/sentry-cache");
+options.setProfileLifecycle(ProfileLifecycle.MANUAL);
+options.setProfilingTracesHz(101);
+```
+
+## How It Works
+
+### Initialization
+- `InitUtil.initializeProfiler(...)` resolves or creates the profiling traces directory
+- `ProfilingServiceLoader.loadContinuousProfiler(...)` uses `ServiceLoader` to find `JavaContinuousProfilerProvider`
+- `AsyncProfilerContinuousProfilerProvider` instantiates `JavaContinuousProfiler`
+- `ProfilingServiceLoader.loadProfileConverter()` separately loads the `JavaProfileConverterProvider`
+
+### Profiling Flow
+
+**Start**
+- Sampling decision is made via `TracesSampler.sampleSessionProfile(...)`
+- Sampling is session-based and cached until `reevaluateSampling()`
+- Scopes and rate limiter are initialized lazily via `initScopes()`
+- Rate limits for `All` or `ProfileChunk` abort startup
+- JFR filename is generated under `profilingTracesDirPath`
+- async-profiler is started with a command like:
+  - `start,jfr,event=wall,nobatch,interval=<interval>,file=<path>`
+- Automatic chunk stop is scheduled after `MAX_CHUNK_DURATION_MILLIS`
+
+**Chunk Rotation**
+- `stop(true)` stops async-profiler and validates the JFR file
+- A `ProfileChunk.Builder` is created with:
+  - current `profilerId`
+  - a fresh `chunkId`
+  - trace file
+  - chunk timestamp
+  - platform `java`
+- Builder is buffered in `payloadBuilders`
+- Chunks are sent if scopes are available
+- Profiling is restarted for the next chunk
+
+**Stop**
+- `MANUAL`: stop immediately, do not restart, reset `profilerId`
+- `TRACE`: decrement `rootSpanCounter`; stop only when it reaches 0
+- `close(...)` also forces shutdown and resets TRACE state
+
+### Sending and Conversion
+- `JavaContinuousProfiler` buffers `ProfileChunk.Builder` instances
+- `sendChunks(...)` builds `ProfileChunk` objects and calls `scopes.captureProfileChunk(...)`
+- `SentryClient.captureProfileChunk(...)` creates an envelope item
+- JVM JFR-to-`SentryProfile` conversion happens in `SentryEnvelopeItem.fromProfileChunk(...)` using the loaded `IProfileConverter`
+- Trace files are deleted in the envelope item path after serialization attempts
+
+## TRACE Mode Lifecycle
+- `rootSpanCounter` increments when sampled root spans start
+- `rootSpanCounter` decrements when root spans finish
+- Profiler runs while `rootSpanCounter > 0`
+- Multiple concurrent sampled transactions can share the same profiling session
+- Be careful when changing lifecycle logic: this area is lock-protected and concurrency-sensitive
+
+## Rate Limiting and Buffering
+
+### Rate Limiting
+- Registers as a `RateLimiter.IRateLimitObserver`
+- If rate limited for `ProfileChunk` or `All`:
+  - profiler stops immediately
+  - it does not auto-restart when the limit expires
+- Startup also checks rate limiting before profiling begins
+
+### Buffering / pre-init behavior
+- JFR files are written to `profilingTracesDirPath` and marked `deleteOnExit()` when a chunk is accepted
+- If scopes are not yet available, `ProfileChunk.Builder`s remain buffered in memory in `payloadBuilders`
+- This commonly matters for profiling that starts before SDK scopes are ready
+- This is not a dedicated durable offline queue owned by the profiler itself; conversion and final send happen later in the normal client/envelope path
+
+## Extending
+
+To add or replace JVM profiler implementations:
+- implement `IContinuousProfiler`
+- implement `JavaContinuousProfilerProvider`
+- register provider in:
+  - `META-INF/services/io.sentry.profiling.JavaContinuousProfilerProvider`
+
+To add or replace JVM profile conversion:
+- implement `IProfileConverter`
+- implement `JavaProfileConverterProvider`
+- register provider in:
+  - `META-INF/services/io.sentry.profiling.JavaProfileConverterProvider`
+
+## Code Locations
+
+Primary implementation:
+- `sentry/src/main/java/io/sentry/IContinuousProfiler.java`
+- `sentry/src/main/java/io/sentry/ProfileChunk.java`
+- `sentry/src/main/java/io/sentry/profiling/ProfilingServiceLoader.java`
+- `sentry/src/main/java/io/sentry/util/InitUtil.java`
+- `sentry/src/main/java/io/sentry/SentryEnvelopeItem.java`
+- `sentry-async-profiler/src/main/java/io/sentry/asyncprofiler/profiling/JavaContinuousProfiler.java`
+- `sentry-async-profiler/src/main/java/io/sentry/asyncprofiler/provider/AsyncProfilerContinuousProfilerProvider.java`
+- `sentry-async-profiler/src/main/java/io/sentry/asyncprofiler/provider/AsyncProfilerProfileConverterProvider.java`
+- `sentry-async-profiler/src/main/java/io/sentry/asyncprofiler/convert/JfrAsyncProfilerToSentryProfileConverter.java`
+
+Tests to read first:
+- `sentry-async-profiler/src/test/java/io/sentry/asyncprofiler/profiling/JavaContinuousProfilerTest.kt`
+- `sentry-async-profiler/src/test/java/io/sentry/asyncprofiler/JavaContinuousProfilingServiceLoaderTest.kt`
+- `sentry-async-profiler/src/test/java/io/sentry/asyncprofiler/convert/JfrAsyncProfilerToSentryProfileConverterTest.kt`
+
+## LLM Guidance
+
+This rule is good enough for orientation, but for actual code changes always verify:
+- the sampling path in `TracesSampler`
+- continuous profiling enablement in `SentryOptions`
+- lifecycle entry points in `Scopes` and `SentryTracer`
+- conversion and file deletion behavior in `SentryEnvelopeItem`
+- existing tests before changing concurrency or lifecycle semantics

.cursor/rules/overview_dev.mdc

@@ -30,7 +30,7 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
 
 - **`scopes`**: Use when working with:
   - Hub/Scope management, forking, or lifecycle
-  - `Sentry.getCurrentScopes()`, `pushScope()`, `withScope()` 
+  - `Sentry.getCurrentScopes()`, `pushScope()`, `withScope()`
   - `ScopeType` (GLOBAL, ISOLATION, CURRENT)
   - Thread-local storage, scope bleeding issues
   - Migration from Hub API (v7 → v8)
@@ -66,6 +66,18 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
   - `SentryMetricsEvent`, `SentryMetricsEvents`
   - `SentryOptions.getMetrics()`, `beforeSend` callback
 
+- **`continuous_profiling_jvm`**: Use when working with:
+  - JVM continuous profiling (`sentry-async-profiler` module)
+  - `IContinuousProfiler`, `JavaContinuousProfiler`
+  - `ProfileChunk`, chunk rotation, JFR file handling
+  - `ProfileLifecycle` (MANUAL vs TRACE modes)
+  - async-profiler integration, ServiceLoader discovery
+  - Rate limiting, offline caching, scopes integration
+
+- **Android profiling**: There is currently no dedicated rule for this area yet.
+  - Inspect the relevant `sentry-android-core` profiling code directly
+  - Fetch other related rules as needed (for example `options`, `offline`, or `api`)
+
 ### Integration & Infrastructure
 - **`opentelemetry`**: Use when working with:
   - OpenTelemetry modules (`sentry-opentelemetry-*`)
@@ -99,11 +111,13 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
    - Public API/apiDump/.api files/binary compatibility/new method → `api`
    - Options/SentryOptions/ExternalOptions/ManifestMetadataReader/sentry.properties → `options`
    - Scope/Hub/forking → `scopes`
-   - Duplicate/dedup → `deduplication` 
+   - Duplicate/dedup → `deduplication`
    - OpenTelemetry/tracing/spans → `opentelemetry`
    - new module/integration/sample → `new_module`
    - Cache/offline/network → `offline`
    - System test/e2e/sample → `e2e_tests`
    - Feature flag/addFeatureFlag/flag evaluation → `feature_flags`
    - Metrics/count/distribution/gauge → `metrics`
    - PR/pull request/stacked PR/stack → `pr`
+   - JVM continuous profiling/async-profiler/JFR/ProfileChunk → `continuous_profiling_jvm`
+   - Android continuous profiling/AndroidProfiler/frame metrics/method tracing → no dedicated rule yet; inspect the code directly

.cursor/rules/pr.mdc

@@ -185,6 +185,8 @@ git push -u origin HEAD
 gh pr create --base main --draft --title "<type>(<scope>): <Topic>" --body "Collection PR for the <Topic> stack. Squash-merge this once all stack PRs are merged."
 ```
 
+**CRITICAL: Do NOT manually update the collection branch.** Never merge, fast-forward, or push stack branch commits into the collection branch. The collection branch stays at its initial position (the empty commit on `main`) until the user merges individual stack PRs into it one by one through GitHub. If you fast-forward the collection branch to include stack commits, GitHub will auto-merge and delete all stack PR branches, destroying the entire stack.
+
 ### Creating a New Stacked PR
 
 1. Start from the tip of the previous stack branch (or the collection branch for the first PR).
@@ -197,35 +199,37 @@ gh pr create --base main --draft --title "<type>(<scope>): <Topic>" --body "Coll
 
 ### Stack List in PR Description
 
-Every PR in the stack must have a stack list **at the top of its description** (before the `## :scroll: Description` section). When a new PR is added, update the description on **all** PRs in the stack.
+Every PR in the stack — **including the collection branch PR** — must have a stack list **at the top of its description** (before the `## :scroll: Description` section). When a new PR is added, update the description on **all** PRs in the stack and on the collection branch PR.
 
 Format:
 
 ```markdown
 ## PR Stack (<Topic>)
 
-- [#5118](https://github.com/getsentry/sentry-java/pull/5118) — Add scope-level attributes API
-- [#5120](https://github.com/getsentry/sentry-java/pull/5120) — Wire scope attributes into LoggerApi and MetricsApi
-- [#5121](https://github.com/getsentry/sentry-java/pull/5121) — Showcase scope attributes in Spring Boot 4 samples
+- #5118
+- #5120
+- #5121
 
 ---
 ```
 
 No status column — GitHub already shows that. The `---` separates the stack list from the rest of the PR description.
 
-To update the PR description, use `--body-file` to avoid shell quoting issues with special characters in the body:
+**Merge method reminder:** On stack PRs (not the collection branch PR), add the following line at the very end of the PR description:
 
-```bash
-# Get current PR description into a temp file
-gh pr view <PR_NUMBER> --json body --jq '.body' > /tmp/pr-body.md
+```markdown
+> ⚠️ **Merge this PR using a merge commit** (not squash). Only the collection branch is squash-merged into main.
+```
 
-# Edit /tmp/pr-body.md to prepend or replace the stack list section
-# (replace everything from "## PR Stack" up to and including the "---" separator,
-#  or prepend before the existing description if no stack list exists yet)
+This does not apply to standalone PRs or the collection branch PR.
 
-# Update the description
-gh pr edit <PR_NUMBER> --body-file /tmp/pr-body.md
-```
+To update the PR description, use `--body-file` to avoid shell quoting issues with special characters in the body.
+
+**Important:** Do not use shell redirects (`>`, `>>`, `|`) or compound commands (`&&`, `||`). These create compound shell expressions that won't match permission patterns. Instead, use the `Write` and `Edit` tools for file manipulation:
+
+1. Read the current body with `gh pr view <PR_NUMBER> --json body --jq '.body'` (the output is returned directly — use the `Write` tool to save it to `/tmp/pr-body.md`)
+2. Use the `Edit` tool to prepend or replace the stack list section in `/tmp/pr-body.md`
+3. Update the description: `gh pr edit <PR_NUMBER> --body-file /tmp/pr-body.md`
 
 ### Merging Stacked PRs (done by the user, not the agent)
 
@@ -237,12 +241,12 @@ Once all stack PRs are merged into the collection branch, the collection PR is *
 
 ### Syncing the Stack
 
-When a base PR changes (e.g. after addressing review feedback on PR 1), merge the changes forward through the stack:
+When a base PR changes (e.g. after addressing review feedback on PR 1), merge the changes forward through the stack **between adjacent stack PR branches only**:
 
 ```bash
 # On the branch for PR 2
 git checkout feat/scope-attributes-logger
-git merge feat/scope-attributes
+git merge feat/scope-attributes-api
 git push
 
 # On the branch for PR 3
@@ -251,4 +255,6 @@ git merge feat/scope-attributes-logger
 git push
 ```
 
+**Never merge into the collection branch.** Syncing only happens between stack PR branches. The collection branch is untouched until the user merges PRs through GitHub.
+
 Prefer merge over rebase — it preserves commit history, doesn't invalidate existing review comments, and avoids the need for force-pushing. Only rebase if explicitly requested.

.github/workflows/agp-matrix.yml

@@ -60,7 +60,7 @@ jobs:
 
       - name: Create AVD and generate snapshot for caching
         if: steps.avd-cache.outputs.cache-hit != 'true'
-        uses: reactivecircus/android-emulator-runner@b530d96654c385303d652368551fb075bc2f0b6b # pin@v2
+        uses: reactivecircus/android-emulator-runner@e89f39f1abbbd05b1113a29cf4db69e7540cae5a # pin@v2
         with:
           api-level: 30
           target: aosp_atd
@@ -79,7 +79,7 @@ jobs:
 
       # We tried to use the cache action to cache gradle stuff, but it made tests slower and timeout
       - name: Run instrumentation tests
-        uses: reactivecircus/android-emulator-runner@b530d96654c385303d652368551fb075bc2f0b6b # pin@v2
+        uses: reactivecircus/android-emulator-runner@e89f39f1abbbd05b1113a29cf4db69e7540cae5a # pin@v2
         with:
           api-level: 30
           target: aosp_atd

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

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/checkout@v6
       - name: Get changed files
         id: changes
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
         with:
           token: ${{ github.token }}
           filters: .github/file-filters.yml

.github/workflows/codeql-analysis.yml

@@ -36,7 +36,7 @@ jobs:
           cache-encryption-key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@89a39a4e59826350b863aa6b6252a07ad50cf83e # pin@v2
+        uses: github/codeql-action/init@0d579ffd059c29b07949a3cce3983f0780820c98 # pin@v2
         with:
           languages: 'java'
 
@@ -45,4 +45,4 @@ jobs:
           ./gradlew buildForCodeQL --no-build-cache
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@89a39a4e59826350b863aa6b6252a07ad50cf83e # pin@v2
+        uses: github/codeql-action/analyze@0d579ffd059c29b07949a3cce3983f0780820c98 # pin@v2