feat(profiling): Add Android ProfilingManager (Perfetto) support

[43jay]

📜 Description

Adds opt-in useProfilingManager option that uses Android's ProfilingManager API (API 35+) for Perfetto-based stack sampling instead of the legacy Debug.startMethodTracingSampling engine.

PerfettoContinuousProfiler is mutually exclusive with AndroidContinuousProfiler — the option gates which implementation is created at init time. The legacy path is unchanged.

Why a new ContinuousProfiler class

The first few commits wire the Perfetto backend into AndroidContinuousProfiler (ported from an earlier branch). The later commits extract a standalone PerfettoContinuousProfiler because:

1. Mutually exclusive — AndroidContinuousProfiler has a lot of state and the if (perfetto) { ... } else { legacy } branching makes paths hard to follow => the two codepaths will never be active at the same time.
2. Threading — a large # different threads are involved and reasoning about locking is harder with two backends in one class

Thread	Callers	Creation site
Caller's thread (main/app)	startProfiler, stopProfiler, close(true), reevaluateSampling	Not created by Sentry
FrameMetrics HandlerThread	Writes frame measurements to PerfettoProfiler's ConcurrentLinkedDeque (code)	new HandlerThread("...SentryFrameMetricsCollector")
SentryExecutorServiceThreadFactory-N	stopInternal(true) — scheduled chunk timer. Also sendChunk() submits work here.	new Thread(r, "SentryExecutorServiceThreadFactory-" + cnt++)
SentryAsyncConnection-N	onRateLimitChanged — inline callback (code)	new Thread(r, "SentryAsyncConnection-" + cnt++)
Timer daemon	onRateLimitChanged — rate limit expiry (code); close(false) — session timeout (code); not a direct caller but CompositePerformanceCollector runs setup() and collect() every 100ms (code)	JDK internal — new Timer(true) in RateLimiter, LifecycleWatcher, CompositePerformanceCollector
OTel span processor	startProfiler(TRACE) (code), stopProfiler(TRACE) (code)	Created by OpenTelemetry SDK — not Sentry-controlled

3. App-start profiling — the legacy profiler has special null-scopes handling for app-start. ProfilingManager doesn't support app-start, so this complexity doesn't apply
4. API level annotations — confining all ProfilingManager call sites to PerfettoContinuousProfiler + PerfettoProfiler means fewer @SuppressLint("NewApi") scattered through AndroidContinuousProfiler

Key files

• SentryOptions.useProfilingManager — opt-in flag, readable from manifest io.sentry.profiling.use-profiling-manager
• PerfettoContinuousProfiler — IContinuousProfiler impl, @RequiresApi(35), delegates to PerfettoProfiler
• PerfettoProfiler — wraps ProfilingManager.requestProfiling(PROFILING_TYPE_STACK_SAMPLING, ...)
• SentryEnvelopeItem.fromPerfettoProfileChunk() — binary envelope format with meta_length header
• AndroidContinuousProfiler — legacy only, no Perfetto references

💡 Motivation and Context

Android's ProfilingManager (API 35+) provides OS-level Perfetto stack sampling. The legacy Debug.startMethodTracingSampling path is preserved unchanged. On API < 35 with useProfilingManager=true, profiling is disabled (no silent fallback).

💚 How did you test it?

• Manual testing on Pixel Fold AVD (API 35) — verified Perfetto chunks captured with content_type: "perfetto"
• Extracted .pftrace files and inspected in Perfetto UI
• Unit tests: PerfettoContinuousProfilerTest (rate limiting), SentryOptionsTest, ManifestMetadataReaderTest, SentryEnvelopeItemTest
• Run: JAVA_HOME=$(/usr/libexec/java_home -v 17) ./gradlew :sentry-android-core:testDebugUnitTest --tests "io.sentry.android.core.PerfettoContinuousProfilerTest"

📝 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.

Testing locally

# Disable ProfilingManager rate limiting (required for repeated testing)
adb shell device_config put profiling_testing rate_limiter.disabled true

# Watch logcat for the file path
adb logcat -s Sentry | grep "ProfilingResult"

# Pull the .pftrace file (can't adb pull from app-private dir, use run-as + cat)
PKG="io.sentry.samples.android"
REMOTE_DIR="/data/user/0/$PKG/files/profiling"
adb shell "run-as $PKG cat '$REMOTE_DIR/<filename>'" > ~/Desktop/profile.pftrace

# Open in https://ui.perfetto.dev/

🔮 Next steps

• Remove CountdownLatch from PerfettoProfiler
• Refactor AndroidContinuousProfilerTest to extend existing test scenarios to PerfettoContinuousProfilerTest
• Verify backend ingest WAE
• Investigate missing thread names in PROFILING_TYPE_STACK_SAMPLING traces (ProfilingManager doesn't seem to include linux.process_stats data source)
• Docs and CHANGELOG update once PR is stable #skip-changelog

[github-actions]

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 873bad3

[github-actions]

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

This PR will not appear in the changelog.

---

_{🤖 This preview updates automatically when you update the PR.}

[sentry]

Sentry Build Distribution

App Name	App ID	Version	Configuration	Install Page
SDK Size	io.sentry.tests.size	8.38.0 (1)	release	Install Build

Configure sentry-android build distribution settings

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	319.08 ms	341.54 ms	22.46 ms
Size	0 B	0 B	0 B

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
6ea4329	309.06 ms	353.48 ms	44.42 ms
d15471f	286.65 ms	314.68 ms	28.03 ms
9054d65	330.94 ms	403.24 ms	72.30 ms
94bff8d	313.23 ms	352.77 ms	39.54 ms
d364ace	382.77 ms	443.21 ms	60.44 ms
ee747ae	358.21 ms	389.41 ms	31.20 ms
5f14e5d	325.76 ms	368.32 ms	42.56 ms
b6cfb57	372.92 ms	507.77 ms	134.85 ms
d15471f	361.89 ms	378.07 ms	16.18 ms
d15471f	379.40 ms	470.76 ms	91.36 ms

App size

Revision	Plain	With Sentry	Diff
6ea4329	1.58 MiB	2.29 MiB	719.82 KiB
d15471f	1.58 MiB	2.13 MiB	559.54 KiB
9054d65	1.58 MiB	2.29 MiB	723.38 KiB
94bff8d	1.58 MiB	2.20 MiB	635.37 KiB
d364ace	1.58 MiB	2.11 MiB	539.75 KiB
ee747ae	1.58 MiB	2.10 MiB	530.95 KiB
5f14e5d	1.58 MiB	2.19 MiB	620.00 KiB
b6cfb57	1.58 MiB	2.28 MiB	718.80 KiB
d15471f	1.58 MiB	2.13 MiB	559.54 KiB
d15471f	1.58 MiB	2.13 MiB	559.54 KiB

Previous results on branch: claude/dreamy-solomon

Startup times

Revision	Plain	With Sentry	Diff
c26f799	319.88 ms	358.02 ms	38.14 ms
7da193d	319.39 ms	375.24 ms	55.85 ms
b3c0878	316.40 ms	345.51 ms	29.11 ms

App size

Revision	Plain	With Sentry	Diff
c26f799	0 B	0 B	0 B
7da193d	0 B	0 B	0 B
b3c0878	0 B	0 B	0 B

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Serialize uses field instead of getter for meta_length
  • SentryEnvelopeItemHeader.serialize() now uses getMetaLength() (captured once in a local) so callable-backed Perfetto chunks correctly emit meta_length in envelope headers.

Or push these changes by commenting:

@cursor push 56eb859503

Preview (56eb859503)

diff --git a/sentry/src/main/java/io/sentry/SentryEnvelopeItemHeader.java b/sentry/src/main/java/io/sentry/SentryEnvelopeItemHeader.java
--- a/sentry/src/main/java/io/sentry/SentryEnvelopeItemHeader.java
+++ b/sentry/src/main/java/io/sentry/SentryEnvelopeItemHeader.java
@@ -219,8 +219,9 @@
     if (itemCount != null) {
       writer.name(JsonKeys.ITEM_COUNT).value(itemCount);
     }
-    if (metaLength != null) {
-      writer.name(JsonKeys.META_LENGTH).value(metaLength);
+    final @Nullable Integer metaLengthValue = getMetaLength();
+    if (metaLengthValue != null) {
+      writer.name(JsonKeys.META_LENGTH).value(metaLengthValue);
     }
     writer.name(JsonKeys.LENGTH).value(getLength());
     if (unknown != null) {

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Lock held during blocking endAndCollect risks ANR

Medium Severity

The scheduled chunk timer acquires the reentrant lock and then calls stopInternal, which calls perfettoProfiler.endAndCollect(). That method calls resultLatch.await(5, SECONDS), blocking the thread while the lock is held. Any call to startProfiler, stopProfiler, isRunning, getChunkId, getProfilerId, or close from another thread (including the main/UI thread) will be blocked for up to 5 seconds. On Android, a 5-second main-thread block causes an ANR. The legacy AndroidContinuousProfiler doesn't have this problem because its endAndCollect is non-blocking.

Additional Locations (1)

• sentry-android-core/src/main/java/io/sentry/android/core/PerfettoProfiler.java#L178-L189

 

^{Reviewed by Cursor Bugbot for commit 10c415f. Configure here.}

[sentry]

Bug: The stopInternal() method holds a lock while calling the blocking endAndCollect() method, which can block the main thread and cause an ANR.
_{Severity: HIGH}

Suggested Fix

The blocking call perfettoProfiler.endAndCollect() should be executed without holding the lock. The lock should be released before the blocking operation and re-acquired if necessary afterward, or the operation should be moved to a background thread to avoid blocking the caller's thread.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location:
sentry-android-core/src/main/java/io/sentry/android/core/PerfettoContinuousProfiler.java#L319-L322

Potential issue: The `stopInternal()` method in `PerfettoContinuousProfiler` is called
with a lock already acquired. It then invokes `perfettoProfiler.endAndCollect()`, which
blocks for up to 5 seconds waiting for a result. If `stopInternal()` is triggered on the
main thread (e.g., when starting a transaction while the profiler is rate-limited or the
device is offline), the main thread will be blocked for the duration of the call. This
can lead to an Application Not Responding (ANR) error on Android, as the ANR threshold
is 5 seconds.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Unconditional shouldStop reset causes unintended profiler continuation
  • shouldStop is now reset only in TRACE starts and in MANUAL starts that actually proceed, so a skipped MANUAL start no longer clears a pending TRACE stop.
• ✅ Fixed: Missing API level guard for PerfettoContinuousProfiler creation
  • setupProfiler now guards useProfilingManager behind an API 35+ check and falls back to NoOpContinuousProfiler on lower API levels to avoid loading Perfetto classes.

Or push these changes by commenting:

@cursor push ce6f706c8b

Preview (ce6f706c8b)

diff --git a/sentry-android-core/src/main/java/io/sentry/android/core/AndroidOptionsInitializer.java b/sentry-android-core/src/main/java/io/sentry/android/core/AndroidOptionsInitializer.java
--- a/sentry-android-core/src/main/java/io/sentry/android/core/AndroidOptionsInitializer.java
+++ b/sentry-android-core/src/main/java/io/sentry/android/core/AndroidOptionsInitializer.java
@@ -337,6 +337,17 @@
           performanceCollector.start(chunkId.toString());
         }
       } else {
+        if (options.isUseProfilingManager()
+            && buildInfoProvider.getSdkInfoVersion() < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
+          options
+              .getLogger()
+              .log(
+                  SentryLevel.INFO,
+                  "useProfilingManager is enabled, but API level is below %d. Continuous profiling is disabled.",
+                  Build.VERSION_CODES.VANILLA_ICE_CREAM);
+          options.setContinuousProfiler(NoOpContinuousProfiler.getInstance());
+          return;
+        }
         final @NotNull SentryFrameMetricsCollector frameMetricsCollector =
             Objects.requireNonNull(
                 options.getFrameMetricsCollector(), "options.getFrameMetricsCollector is required");

diff --git a/sentry-android-core/src/main/java/io/sentry/android/core/PerfettoContinuousProfiler.java b/sentry-android-core/src/main/java/io/sentry/android/core/PerfettoContinuousProfiler.java
--- a/sentry-android-core/src/main/java/io/sentry/android/core/PerfettoContinuousProfiler.java
+++ b/sentry-android-core/src/main/java/io/sentry/android/core/PerfettoContinuousProfiler.java
@@ -107,7 +107,6 @@
       final @NotNull ProfileLifecycle profileLifecycle,
       final @NotNull TracesSampler tracesSampler) {
     try (final @NotNull ISentryLifecycleToken ignored = lock.acquire()) {
-      shouldStop = false;
       if (shouldSample) {
         isSampled = tracesSampler.sampleSessionProfile(SentryRandom.current().nextDouble());
         shouldSample = false;
@@ -118,6 +117,7 @@
       }
       switch (profileLifecycle) {
         case TRACE:
+          shouldStop = false;
           activeTraceCount = Math.max(0, activeTraceCount); // safety check.
           activeTraceCount++;
           break;
@@ -128,6 +128,7 @@
                 "Unexpected call to startProfiler(MANUAL) while profiler already running. Skipping.");
             return;
           }
+          shouldStop = false;
           break;
       }
       if (!isRunning()) {

diff --git a/sentry-android-core/src/test/java/io/sentry/android/core/AndroidOptionsInitializerTest.kt b/sentry-android-core/src/test/java/io/sentry/android/core/AndroidOptionsInitializerTest.kt
--- a/sentry-android-core/src/test/java/io/sentry/android/core/AndroidOptionsInitializerTest.kt
+++ b/sentry-android-core/src/test/java/io/sentry/android/core/AndroidOptionsInitializerTest.kt
@@ -376,7 +376,16 @@
     assertTrue(fixture.sentryOptions.continuousProfiler is AndroidContinuousProfiler)
   }
 
+  @Config(sdk = [34])
   @Test
+  fun `init with profiling manager below API 35 sets no-op continuous profiler`() {
+    fixture.initSut(configureOptions = { isUseProfilingManager = true }, useRealContext = true)
+
+    assertEquals(NoOpTransactionProfiler.getInstance(), fixture.sentryOptions.transactionProfiler)
+    assertEquals(NoOpContinuousProfiler.getInstance(), fixture.sentryOptions.continuousProfiler)
+  }
+
+  @Test
   fun `init with profilesSampleRate should set Android transaction profiler`() {
     fixture.initSut(configureOptions = { profilesSampleRate = 1.0 })
 

diff --git a/sentry-android-core/src/test/java/io/sentry/android/core/PerfettoContinuousProfilerTest.kt b/sentry-android-core/src/test/java/io/sentry/android/core/PerfettoContinuousProfilerTest.kt
--- a/sentry-android-core/src/test/java/io/sentry/android/core/PerfettoContinuousProfilerTest.kt
+++ b/sentry-android-core/src/test/java/io/sentry/android/core/PerfettoContinuousProfilerTest.kt
@@ -132,4 +132,24 @@
       "Profiler should continue running after chunk restart — shouldStop must be reset on start",
     )
   }
+
+  @Test
+  fun `manual start while trace profiling is running does not cancel pending trace stop`() {
+    val profiler = fixture.getSut()
+
+    profiler.startProfiler(ProfileLifecycle.TRACE, fixture.mockTracesSampler)
+    assertTrue(profiler.isRunning)
+
+    profiler.stopProfiler(ProfileLifecycle.TRACE)
+    profiler.startProfiler(ProfileLifecycle.MANUAL, fixture.mockTracesSampler)
+
+    fixture.executor.runAll()
+
+    assertFalse(profiler.isRunning)
+    verify(fixture.mockLogger)
+      .log(
+        eq(SentryLevel.WARNING),
+        eq("Unexpected call to startProfiler(MANUAL) while profiler already running. Skipping."),
+      )
+  }
 }

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 873bad3. Configure here.}

[cursor]

Unconditional shouldStop reset causes unintended profiler continuation

Medium Severity

shouldStop = false is set unconditionally at the top of startProfiler(), before any lifecycle checks. When startProfiler(MANUAL) is called while the profiler is already running from a TRACE lifecycle, the method resets shouldStop to false but then returns early at line 129 with a "Skipping" warning. This silently cancels a pending stop request from a prior stopProfiler(TRACE) call, causing the profiler to restart indefinitely at chunk boundaries instead of stopping as intended.

 

^{Reviewed by Cursor Bugbot for commit 873bad3. Configure here.}

[cursor]

Missing API level guard for PerfettoContinuousProfiler creation

High Severity

PerfettoContinuousProfiler is created when isUseProfilingManager() is true with no API level check. On API < 35, when ensureProfiler() eventually evaluates the supplier, it loads PerfettoProfiler which references ProfilingManager (API 35+), causing a NoClassDefFoundError crash. The PR description states profiling is "disabled" on API < 35 but no code enforces this.

 

^{Reviewed by Cursor Bugbot for commit 873bad3. Configure here.}