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

[43jay]

📜 Description

Adds support for Android's ProfilingManager API (API 35+), which captures continuous profiles (profile chunks) using OS-level Perfetto stack sampling instead of the legacy Debug.startMethodTracingSampling engine.

Behavior by API level:

• API 35+ — Perfetto profiling via ProfilingManager is used automatically. No configuration needed.
• API < 35 — the legacy Debug-based profiler is used, controlled by the new enableLegacyProfiling option.

⚙️ New options

Option	Manifest key	Default	Description
enableLegacyProfiling	io.sentry.profiling.enable-legacy-profiling	true	Enables the legacy Debug-based profiler on API < 35. Set to false to disable profiling on those devices. Has no effect on API 35+. Will be deprecated in the next major and removed after.

⚠️ Limitations

• Perfetto profiling requires API 35+. On API < 35 with enableLegacyProfiling = false, no profiling data is collected (no silent fallback).
• Only continuous profiling (profile chunks) is supported via ProfilingManager — transaction-based (legacy) profiling is unaffected.
• App-start profiling is not supported on the Perfetto path (ProfilingManager doesn't support it).
• Thread names may be missing in captured traces (ProfilingManager doesn't include linux.process_stats data).

💡 Motivation and Context

💚 How did you test it?

• Unit tests
• Manual testing on Pixel Fold AVD (API 35) — verified Perfetto chunks captured with content_type: "perfetto" and inspected in Perfetto UI.

📝 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.
• Review from the native team if needed.

#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 9d3cb80

[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]

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.49.0 (1)	release

⚙️ sentry-android Build Distribution Settings

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	310.51 ms	358.10 ms	47.59 ms
Size	0 B	0 B	0 B

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
382d6c1	306.85 ms	368.70 ms	61.85 ms
e63ad34	323.67 ms	390.33 ms	66.67 ms
91bb874	310.68 ms	359.24 ms	48.56 ms
5865051	324.24 ms	356.02 ms	31.78 ms
806307f	357.85 ms	424.64 ms	66.79 ms
b193867	331.08 ms	397.06 ms	65.98 ms
0eaac1e	322.53 ms	389.31 ms	66.78 ms
6405ec5	310.88 ms	354.56 ms	43.69 ms
d15471f	310.66 ms	368.19 ms	57.53 ms
951caf7	323.66 ms	392.82 ms	69.16 ms

App size

Revision	Plain	With Sentry	Diff
382d6c1	1.58 MiB	2.29 MiB	719.85 KiB
e63ad34	0 B	0 B	0 B
91bb874	1.58 MiB	2.13 MiB	559.07 KiB
5865051	0 B	0 B	0 B
806307f	1.58 MiB	2.10 MiB	533.42 KiB
b193867	1.58 MiB	2.19 MiB	620.00 KiB
0eaac1e	1.58 MiB	2.19 MiB	619.17 KiB
6405ec5	1.58 MiB	2.12 MiB	552.23 KiB
d15471f	1.58 MiB	2.13 MiB	559.54 KiB
951caf7	1.58 MiB	2.13 MiB	558.77 KiB

Previous results on branch: claude/dreamy-solomon

Startup times

Revision	Plain	With Sentry	Diff
e729c4a	360.54 ms	459.90 ms	99.36 ms
b4857f6	314.92 ms	358.61 ms	43.69 ms

App size

Revision	Plain	With Sentry	Diff
e729c4a	0 B	0 B	0 B
b4857f6	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]

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

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

Autofix Details

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

[romtsn]

A couple of low-to-medium comments, but nothing blocking really (except the executor service submit on the same executor service thread, which can result in an endless loop I think).

The biggest question to me if we should get rid of the flag altogether and just use ProfilingManager by default on API 35+? Or we could keep it but make it true by default, just to have a backdoor to disable it, if something goes terribly wrong.

Dismissing, as I took over the PR

[romtsn]

Decision: Option 4 — enableLegacyProfiling flag, ProfilingManager always-on for API 35+

After discussion in the SDK team (referencing telemetry context: ~49.5% of Android events are already from Android 15+ / API 35+, and the top profiling customer by volume is fully on the native Android SDK), we've aligned on option 4:

• ProfilingManager is the default profiler on API 35+ — no opt-in required.
• A new enableLegacyProfiling option (defaults to true) allows customers to keep legacy profiling on API < 35 during this transitional period.
• enableLegacyProfiling is dropped in the next major — at that point legacy profiling is gone entirely and ProfilingManager is the only path.

This avoids forcing an opt-in for the new (better) path, preserves continuity for sub-API-35 devices in the interim, and gives a clean deprecation timeline. Mixing profilers (options 2 or 3) was ruled out due to crash risk and sampling rate complexity.

[cursor]

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

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 9c9715f. Configure here.}

[cursor]

Null app context crashes profiling

Medium Severity

setupProfiler assigns context.getApplicationContext() directly into a @NotNull variable and captures it in the PerfettoProfiler factory. That call can return null (which is why ContextUtils.getApplicationContext exists and is used elsewhere in this file), so the first startInternal can throw when creating PerfettoProfiler.

 

^{Reviewed by Cursor Bugbot for commit 9c9715f. Configure here.}