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 10c415f

[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.39 ms	375.24 ms	55.85 ms
Size	0 B	0 B	0 B

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
d15471f	369.38 ms	459.08 ms	89.70 ms
9fbb112	359.71 ms	421.85 ms	62.14 ms
1df7eb6	397.04 ms	429.64 ms	32.60 ms
ee747ae	400.46 ms	423.61 ms	23.15 ms
ee747ae	357.79 ms	421.84 ms	64.05 ms
b193867	331.08 ms	397.06 ms	65.98 ms
a416a65	333.78 ms	410.37 ms	76.59 ms
b193867	319.59 ms	403.09 ms	83.50 ms
b6cfb57	372.92 ms	507.77 ms	134.85 ms
ee35ac3	346.83 ms	435.48 ms	88.65 ms

App size

Revision	Plain	With Sentry	Diff
d15471f	1.58 MiB	2.13 MiB	559.54 KiB
9fbb112	1.58 MiB	2.11 MiB	539.18 KiB
1df7eb6	1.58 MiB	2.10 MiB	532.97 KiB
ee747ae	1.58 MiB	2.10 MiB	530.95 KiB
ee747ae	1.58 MiB	2.10 MiB	530.95 KiB
b193867	1.58 MiB	2.19 MiB	620.00 KiB
a416a65	1.58 MiB	2.12 MiB	555.26 KiB
b193867	1.58 MiB	2.19 MiB	620.00 KiB
b6cfb57	1.58 MiB	2.28 MiB	718.80 KiB
ee35ac3	1.58 MiB	2.13 MiB	558.77 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
b3c0878	316.40 ms	345.51 ms	29.11 ms

App size

Revision	Plain	With Sentry	Diff
c26f799	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]

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

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

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

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

[43jay]

love this cursor bot thing. was planning this work already -> see todos

[cursor]

getMetaLength returns -1 instead of null before evaluation

Medium Severity

The metaLength is initialized as new AtomicInteger(-1), and the callable metaLength::get always returns a non-null Integer (autoboxed from int). So getMetaLength() never returns null when the callable is set — it returns -1 before data evaluation. In SentryEnvelopeItemHeader.serialize(), getMetaLength() is called before getLength(), so if the header is ever serialized without item.getData() being called first, meta_length: -1 is written. The current JsonSerializer flow protects against this, but the contract of returning @Nullable Integer is violated.

Additional Locations (1)

• sentry/src/main/java/io/sentry/SentryEnvelopeItemHeader.java#L218-L222

 

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