Update Android continuous profiling instructions and options (#13219)

* updated Android continuous profiling instructions and options
* Added deprecation notes for transaction-based profiling

Author: stefanosiano

docs/platforms/android/configuration/options.mdx

@@ -301,54 +301,56 @@ Set this boolean to `false` to disable tracing for `OPTIONS` requests. This opti
 
 </ConfigKey>
 
-## Profiling Options
+## UI Profiling Options
 
-<ConfigKey name="profiles-sample-rate">
+<Alert title="Note">
 
-A number between `0` and `1`, controlling the percentage chance a given profile will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies only to sampled transactions created in the app. Either this or <PlatformIdentifier name="profiles-sampler" /> must be defined to enable transaction profiling. Don't set it if you want to use <PlatformLink to="/profiling/#continuous-profiling">Continuous Profiling</PlatformLink>.
+UI Profiling requires SDK versions `8.7.0` or higher. Lower versions can use the <PlatformLink to="/configuration/options/#transaction-based-profiling-options">transaction-based profiling</PlatformLink>.
 
-</ConfigKey>
+</Alert>
 
-<ConfigKey name="profiles-sampler">
+<ConfigKey name="profile-session-sample-rate">
 
-A function responsible for determining the percentage chance a given profile will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering profiles, by returning 0 for those that are unwanted. Either this or <PlatformIdentifier name="profiles-sample-rate" /> must be defined to enable transaction profiling. Don't set it if you want to use <PlatformLink to="/profiling/#continuous-profiling">Continuous Profiling</PlatformLink>.
+A number between `0` and `1`, controlling the percentage chance that the session will be profiled. `0` represents 0% while `1` represents 100%. The default is null (disabled).
 
 </ConfigKey>
 
-<ConfigKey name="enable-app-start-profiling">
+<ConfigKey name="profile-lifecycle">
 
-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="profiles-sample-rate" /> or <PlatformIdentifier name="profiles-sampler" /> must be defined.
+Whether the UI profiling lifecycle is controlled manually or based on the trace lifecycle. Possible values are:
+
+- `manual`: **default** Profiler must be started and stopped through `Sentry.startProfiler()` and `Sentry.stopProfiler()` APIs
+- `trace`: Profiler is started and stopped automatically whenever a sampled trace starts or finishes
 
 </ConfigKey>
 
-## Continuous Profiling Options
+<ConfigKey name="start-profiler-on-app-start">
 
-<Alert>
+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="profile-session-sample-rate" /> must be defined.
 
-This feature is experimental and may have bugs.
+- 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
 
-</Alert>
+</ConfigKey>
 
-<ConfigKey name="profile-session-sample-rate">
+## Transaction-Based Profiling Options
 
-A number between `0` and `1`, controlling the percentage chance the session will be profiled. `0` represents 0% while `1` represents 100%. The default is null (disabled). <PlatformIdentifier name="profiles-sampler" /> and <PlatformIdentifier name="profiles-sample-rate" /> must not be set to enable <PlatformLink to="/profiling/#continuous-profiling">Continuous Profiling</PlatformLink>.
+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.
 
-</ConfigKey>
+<ConfigKey name="profiles-sample-rate">
 
-<ConfigKey name="profile-lifecycle">
+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.
 
-Whether the profiling lifecycle is controlled manually or based on the trace lifecycle. Possible values are:
+</ConfigKey>
 
-- `manual`: **default** Profiler must be started and stopped through `Sentry.startProfiler()` and `Sentry.stopProfiler()` APIs
-- `trace`: Profiler is started and stopped automatically whenever a sampled trace starts and finishes
+<ConfigKey name="profiles-sampler">
 
-</ConfigKey>
+A function responsible for determining the percentage chance that a given profile will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering profiles, by returning 0 for those that are unwanted. Either this or <PlatformIdentifier name="profiles-sample-rate" /> must be defined to enable transaction profiling. Setting this option will enable the legacy profiler.
 
-<ConfigKey name="start-profiler-on-app-start">
+</ConfigKey>
 
-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="profile-session-sample-rate" /> must be defined.
+<ConfigKey name="enable-app-start-profiling">
 
-- 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
+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.
 
 </ConfigKey>

docs/platforms/android/index.mdx

@@ -30,10 +30,7 @@ Select which Sentry features you'd like to install in addition to Error Monitori
   options={[
     'error-monitoring',
     'performance',
-    {
-      id: 'profiling',
-      checked: false
-    },
+    'profiling',
     'session-replay'
   ]}
 />
@@ -83,13 +80,13 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp
   <meta-data android:name="io.sentry.send-default-pii" android:value="true" />
   <!-- Enable the performance API by setting a sample-rate, adjust in production env -->
   <meta-data android:name="io.sentry.traces.sample-rate" android:value="1.0" />
-  <!-- Enable profiling, adjust in production env. See https://docs.sentry.io/platforms/android/profiling for more info -->
+  <!-- Enable profiling, adjust in production env. This is evaluated only once per session -->
   <meta-data android:name="io.sentry.traces.profiling.session-sample-rate" android:value="1.0" />
-  <!-- Set profiling lifecycle, can be `manual` or `trace` -->
-  <meta-data android:name="io.sentry.traces.profiling.lifecycle" android:value="manual" />
+  <!-- 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" />
-  <!-- record session replays for 100% of errors and 10% of sessions -->
+  <!-- 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" />
   <meta-data android:name="io.sentry.session-replay.session-sample-rate" android:value="0.1" />
 </application>
@@ -108,15 +105,11 @@ import io.sentry.Sentry;
 public class MyActivity extends AppCompatActivity {
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
-    // Any code running after this line will be
-    //profiled until Sentry.stopProfiler() is called.
-    Sentry.startProfiler();
     try {
       throw new Exception("This is a test.");
     } catch (Exception e) {
       Sentry.captureException(e);
     }
-    Sentry.stopProfiler();
   }
 }
 ```
@@ -129,15 +122,11 @@ import io.sentry.Sentry
 class MyActivity : AppCompatActivity() {
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
-    // Any code running after this line will be
-    //profiled until Sentry.stopProfiler() is called.
-    Sentry.startProfiler()
     try {
       throw Exception("This is a test.")
     } catch (e: Exception) {
       Sentry.captureException(e)
     }
-    Sentry.stopProfiler()
   }
 }
 ```