docs(android): Introduce Android ProfilingManager options

docs/platforms/android/configuration/options.mdx

@@ -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.51.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 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.
+
+</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).
@@ -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
@@ -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.

docs/platforms/android/index.mdx

@@ -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>
@@ -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 -->

docs/platforms/android/manual-setup/index.mdx

@@ -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" />
@@ -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
@@ -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);