Skip to content

docs(android): Introduce Android ProfilingManager options #18481

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
markushi wants to merge 6 commits into
base: master
Choose a base branch
from
Open

docs(android): Introduce Android ProfilingManager options #18481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e7bb0fa
docs(android): Introduce Android ProfilingManager options
markushi Jun 18, 2026
3ea89e4
docs(android): Note device/OS rate limiting for UI Profiling
markushi Jun 19, 2026
330270b
docs(android): Address review feedback on profiling pages
markushi Jun 29, 2026
9b66adb
docs(android): Make ProfilingManager automatic, add enableLegacyProfi…
markushi Jun 29, 2026
82c906b
docs(android): Inline profiling alert to match review formatting
markushi Jun 29, 2026
2e86d2e
docs(android): Note enableLegacyProfiling=false disables transaction-…
markushi Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion docs/platforms/android/configuration/options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,16 @@ UI Profiling requires SDK versions `8.7.0` or higher. Lower versions can use the

</Alert>

<SdkOption name="enableLegacyProfiling" type="bool" defaultValue="true" availableSince="8.47.0">

On devices running Android 15 (API level 35) or higher, UI Profiling always uses the Android <Link to="https://developer.android.com/reference/android/os/ProfilingManager">ProfilingManager</Link> to capture <Link to="https://perfetto.dev/">Perfetto</Link> traces. On older devices, this option controls whether the SDK falls back to the <PlatformLink to="/profiling/legacy">legacy `tracer` backend</PlatformLink>. When `true` (the default), the legacy profiler runs on devices below API level 35. Set it to `false` to disable profiling on those devices entirely.

Setting this option to `false` also disables <PlatformLink to="/configuration/options/#transaction-based-profiling-options">transaction-based profiling</PlatformLink> (`profilesSampleRate`/`profilesSampler`) on all devices, since transaction-based profiling always relies on the legacy profiler and is not supported by the ProfilingManager (Perfetto) backend.

This option is deprecated and will be removed in the next major release, when only the ProfilingManager (Perfetto) backend will remain.

@romtsn romtsn Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This option is deprecated and will be removed in the next major release, when only the ProfilingManager (Perfetto) backend will remain.
This option will be deprecated in the next major release and will be removed in the one after next, when only the ProfilingManager (Perfetto) backend will remain.

We continued the discussion while you were away and turns out there's still quite some usage of the old tracer among our biggest orgs, so we've decided to keep the option in the next major (turn it to false by default and deprecate it), and only remove the option and the legacy tracer in the one after. https://sentry.slack.com/archives/C089VFRB8N9/p1781857096845799?thread_ts=1781851862.250829&cid=C089VFRB8N9

@runningcode runningcode Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

edit: major ;)


</SdkOption>

<SdkOption name="profileSessionSampleRate" type="float" availableSince="8.7.0">

A number between `0` and `1`, controlling the percentage chance that the session will be profiled. (`0` represents 0%, `1` represents 100%.) The default is null (disabled).
Expand All @@ -370,7 +380,7 @@ Whether the UI profiling lifecycle is controlled manually or based on the trace

<SdkOption name="startProfilerOnAppStart" type="bool" defaultValue="false" availableSince="8.7.0">

A boolean value that determines whether the app start process will be profiled. When true, the startup process, including ContentProviders, Application, and first Activity creation, will be profiled. Note that <PlatformIdentifier name="profileSessionSampleRate" /> must be defined.
A boolean value that determines whether the app start process will be profiled. When true, the startup process, including ContentProviders, Application, and first Activity creation, will be profiled. Note that <PlatformIdentifier name="profileSessionSampleRate" /> must be defined. App start profiling is only supported by the <PlatformLink to="/profiling/legacy">legacy profiler</PlatformLink>, which runs on devices below Android 15 (API level 35). It has no effect with the ProfilingManager (Perfetto) backend used on API level 35 and higher.

- If profileLifecycle is set to `manual`: profiling is started automatically on startup and stopProfiler must be called manually whenever the app startup is deemed to be completed
- If profileLifecycle is set to `trace`: profiling is started automatically on startup, and will automatically be stopped when the root span that is associated with app startup ends
Expand All @@ -395,6 +405,12 @@ When enabled, the SDK assigns a static fingerprint to ANR events whose stack tra

This mode will eventually be deprecated, and it's recommended to upgrade to <PlatformLink to="/configuration/options/#ui-profiling-options">UI Profiling</PlatformLink>. The same behaviour, without the 30 seconds limitation, can be achieved with the `trace` <PlatformLink to="/configuration/options/#profile-lifecycle">profile lifecycle</PlatformLink> option. In order to upgrade to UI Profiling, you also need to remove the transaction-based options from your configuration.

<Alert level="warning">

Transaction-based profiling always uses the legacy profiler and is not supported by the ProfilingManager (Perfetto) backend. Setting <PlatformLink to="/configuration/options/#enableLegacyProfiling">`enableLegacyProfiling`</PlatformLink> to `false` therefore disables transaction-based profiling on all devices, and no profiling data will be collected. Use <PlatformLink to="/configuration/options/#profileSessionSampleRate">`profileSessionSampleRate`</PlatformLink> for UI (continuous) Profiling instead.

</Alert>

<SdkOption name="profilesSampleRate" type="float">

A number between `0` and `1`, controlling the percentage chance that a given profile will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies only to sampled transactions created in the app. Setting this option will enable the legacy profiler.
Expand Down
6 changes: 2 additions & 4 deletions docs/platforms/android/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ Select which Sentry features you'd like to install in addition to Error Monitori

<OnboardingOption optionId="profiling">

<Alert level="warning">
Profiling uses the Android runtime's `tracer` under the hood to sample threads. There are known issues that this `tracer` can cause crashes in certain circumstances. See this <PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated">troubleshooting</PlatformLink> entry for more information.
<Alert level="info">
On Android 15 (API level 35) and higher, profiling uses the Android <Link to="https://developer.android.com/reference/android/os/ProfilingManager">ProfilingManager</Link> to capture <Link to="https://perfetto.dev/">Perfetto</Link> traces. On older devices, the SDK automatically falls back to the <PlatformLink to="/profiling/legacy">legacy profiler</PlatformLink>.
</Alert>

</OnboardingOption>
Expand Down Expand Up @@ -128,8 +128,6 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp
<meta-data android:name="io.sentry.traces.profiling.session-sample-rate" android:value="1.0" />
<!-- Set profiling lifecycle, can be `manual` (controlled through `Sentry.startProfiler()` and `Sentry.stopProfiler()`) or `trace` (automatically starts and stop a profile whenever a sampled trace starts and finishes) -->
<meta-data android:name="io.sentry.traces.profiling.lifecycle" android:value="trace" />
<!-- Enable profiling on app start -->
<meta-data android:name="io.sentry.traces.profiling.start-on-app-start" android:value="true" />
<!-- ___PRODUCT_OPTION_END___ profiling -->
<!-- ___PRODUCT_OPTION_START___ logs -->
<!-- Enable logs to be sent to Sentry -->
Expand Down
6 changes: 0 additions & 6 deletions docs/platforms/android/manual-setup/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,6 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp
<meta-data android:name="io.sentry.traces.profiling.session-sample-rate" android:value="1.0" />
<!-- Set profiling mode. For more info see https://docs.sentry.io/platforms/android/profiling/#enabling-ui-profiling -->
<meta-data android:name="io.sentry.traces.profiling.lifecycle" android:value="trace" />
<!-- Enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes -->
<meta-data android:name="io.sentry.traces.profiling.start-on-app-start" android:value="true" />

<!-- record session replays for 100% of errors and 10% of sessions -->
<meta-data android:name="io.sentry.session-replay.on-error-sample-rate" android:value="1.0" />
Expand Down Expand Up @@ -159,8 +157,6 @@ class MyApplication : Application() {
options.profileSessionSampleRate = 1.0
// set profiling mode. For more info see https://docs.sentry.io/platforms/android/profiling/#enabling-ui-profiling
options.profileLifecycle = ProfileLifecycle.TRACE
// enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes
options.isStartProfilerOnAppStart = true
// record session replays for 100% of errors and 10% of sessions
options.sessionReplay.sessionSampleRate = 0.1
options.sessionReplay.onErrorSampleRate = 1.0
Expand Down Expand Up @@ -218,8 +214,6 @@ public class MyApplication extends Application {
options.setProfileSessionSampleRate(1.0);
// set profiling mode. For more info see https://docs.sentry.io/platforms/android/profiling/#enabling-ui-profiling
options.setProfileLifecycle(ProfileLifecycle.TRACE);
// enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes
options.setStartProfilerOnAppStart(true);
// record session replays for 100% of errors and 10% of sessions
options.getSessionReplay().setSessionSampleRate(0.1);
options.getSessionReplay().setOnErrorSampleRate(1.0);
Expand Down
Loading
Loading