add instructions to setup Android continuous profiling (#11872)

stefanosiano · web-flow · commit 11f34f9d83a7 · 2025-03-25T14:07:49.000Z
* add instructions to setup Android continuous profiling
diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx
@@ -305,13 +305,13 @@ Set this boolean to `false` to disable tracing for `OPTIONS` requests. This opti
 
 <ConfigKey name="profiles-sample-rate">
 
-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 profiling.
+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>.
 
 </ConfigKey>
 
 <ConfigKey name="profiles-sampler">
 
-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 profiling.
+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>.
 
 </ConfigKey>
 
@@ -320,3 +320,35 @@ A function responsible for determining the percentage chance a given profile wil
 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.
 
 </ConfigKey>
+
+## Continuous Profiling Options
+
+<Alert>
+
+This feature is experimental and may have bugs.
+
+</Alert>
+
+<ConfigKey name="profile-session-sample-rate">
+
+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>.
+
+</ConfigKey>
+
+<ConfigKey name="profile-lifecycle">
+
+Whether the 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 and finishes
+
+</ConfigKey>
+
+<ConfigKey name="start-profiler-on-app-start">
+
+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.
+
+- 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
+
+</ConfigKey>
diff --git a/docs/platforms/android/index.mdx b/docs/platforms/android/index.mdx
@@ -75,16 +75,20 @@ The wizard will prompt you to log in to Sentry. It'll then automatically do the
 Configuration is done via the application `AndroidManifest.xml`. Here's an example config which should get you started:
 
 
-```xml {filename:AndroidManifest.xml} {"onboardingOptions": {"performance": "6-7", "profiling": "8-9", "session-replay": "10-12"}}
+```xml {filename:AndroidManifest.xml} {"onboardingOptions": {"performance": "6-7", "profiling": "8-13", "session-replay": "14-16"}}
 <application>
   <!-- Required: set your sentry.io project identifier (DSN) -->
   <meta-data android:name="io.sentry.dsn" android:value="___PUBLIC_DSN___" />
   <!-- Add data like request headers, user ip address and device name, see https://docs.sentry.io/platforms/android/data-management/data-collected/ for more info -->
   <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 -->
+  <!-- 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 when starting transactions, adjust in production env -->
-  <meta-data android:name="io.sentry.traces.profiling.sample-rate" android:value="1.0" />
+  <!-- Enable profiling, adjust in production env. See https://docs.sentry.io/platforms/android/profiling for more info -->
+  <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" />
+  <!-- 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 -->
   <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" />
@@ -104,11 +108,15 @@ 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();
   }
 }
 ```
@@ -121,11 +129,15 @@ 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()
   }
 }
 ```
diff --git a/docs/platforms/android/profiling/index.mdx b/docs/platforms/android/profiling/index.mdx
@@ -68,3 +68,82 @@ The SDK won't run app start profiling the very first time the app runs, as the S
 The SDK will set the `isForNextAppStart` flag in `TransactionContext` if app start profiling is enabled.
 
 </Alert>
+
+## Continuous Profiling
+
+<Alert>
+
+This feature is experimental and may have bugs.
+
+</Alert>
+
+_(New in version 8.5.0)_
+
+The current profiling implementation stops the profiler automatically after 30 seconds (unless you manually stop it earlier). Naturally, this limitation makes it difficult to get full coverage of your app's execution. We now offer an experimental continuous mode, where profiling data is periodically uploaded while running, with no limit to how long the profiler may run.
+
+Previously, profiles only ran in tandem with performance transactions that were started either automatically or manually with `Sentry.startTransaction`. Now, you can start and stop the profiler directly with `Sentry.startProfiler` and `Sentry.stopProfiler`. You can also start a profile at app launch by setting `SentryOptions.startProfilerOnAppStart = true` in your call to `SentryAndroid.init`.
+
+Continuous profiling requires only the `SentryOptions.profileSessionSampleRate` option to be set when you start the SDK to opt in. If you had previously set `SentryOptions.profilesSampleRate` or `SentryOptions.profilesSampler` to use transaction-based profiling, then remove those lines of code from your configuration.
+
+There are two ways to start the profiler: manually, calling `Sentry.startProfiler` and `Sentry.stopProfiler` to start and stop the profiler, or automatically whenever a sampled trace starts and finishes. The latter behaviour is very similar to the current profiling implementation. You can control this behaviour setting `SentryOptions.profileLifecycle` to `manual` or `trace` in your call to `SentryAndroid.init`.
+
+<Alert title="Note">
+
+Continuous profiling has implications for your org's billing structure. This feature is only available for subscription plans that enrolled after June 5, 2024.
+
+</Alert>
+
+```xml {filename:AndroidManifest.xml}
+<application>
+  <meta-data android:name="io.sentry.traces.profiling.session-sample-rate" android:value="1.0" />
+  <meta-data android:name="io.sentry.traces.profiling.lifecycle" android:value="manual" />
+  <meta-data android:name="io.sentry.traces.profiling.start-on-app-start" android:value="true" />
+</application>
+```
+
+Or, if you are manually instrumenting Sentry:
+
+
+```java {tabTitle:Java}
+import io.sentry.android.core.SentryAndroid;
+
+SentryAndroid.init(this, options -> {
+  options.setDsn("___PUBLIC_DSN___");
+  // Currently under experimental options:
+  options.getExperimental().setProfileSessionSampleRate(1.0);
+  // In manual mode, you need to start and stop the profiler manually using Sentry.startProfiler and Sentry.stopProfiler
+  // In trace mode, the profiler will start and stop automatically whenever a sampled trace starts and finishes
+  options.getExperimental().setProfileLifecycle(ProfileLifecycle.MANUAL);
+  // Start profiling automatically as early as possible, to capture app startup
+  // If profileLifecycle is set to `manual`: stopProfiler must be called manually when the app startup is completed
+  // If profileLifecycle is set to `trace`: profiling will automatically be stopped when the app start root span ends
+  options.getExperimental().setStartProfilerOnAppStart(true);
+});
+// Start profiling
+Sentry.startProfiler();
+
+// After all profiling is done, stop the profiler. Profiles can last indefinitely if not stopped.
+Sentry.stopProfiler();
+```
+
+```kotlin {tabTitle:Kotlin}
+import io.sentry.android.core.SentryAndroid
+
+SentryAndroid.init(this) { options ->
+  options.dsn = "___PUBLIC_DSN___"
+  // Currently under experimental options:
+  options.experimental.profileSessionSampleRate = 1.0
+  // In manual mode, you need to start and stop the profiler manually using Sentry.startProfiler and Sentry.stopProfiler
+  // In trace mode, the profiler will start and stop automatically whenever a sampled trace starts and finishes
+  options.experimental.profileLifecycle = ProfileLifecycle.MANUAL
+  // Start profiling automatically as early as possible, to capture app startup
+  // If profileLifecycle is set to `manual`: stopProfiler must be called manually when the app startup is completed
+  // If profileLifecycle is set to `trace`: profiling will automatically be stopped when the app start root span ends
+  options.experimental.startProfilerOnAppStart = true
+}
+// Start profiling
+Sentry.startProfiler()
+
+// After all profiling is done, stop the profiler. Profiles can last indefinitely if not stopped.
+Sentry.stopProfiler()
+```
diff --git a/docs/platforms/apple/common/profiling/index.mdx b/docs/platforms/apple/common/profiling/index.mdx
@@ -113,6 +113,6 @@ Previously, profiles only ran in tandem with performance transactions that were
 
 Continuous profiling mode is enabled by default, requiring no changes to `SentryOptions` when you start the SDK to opt in. If you had previously set `SentryOptions.profilesSampleRate` or `SentryOptions.profilesSampler` to use transaction-based profiling, then remove those lines of code from your configuration.
 
-These new APIs do not offer any sampling functionality—every call to start the profiler will start it, and the same goes for launch profiles if you've configured that. If you are interested in reducing the amount of profiles that run, you must take care to do it at the callsites.
+These new APIs do not offer any sampling functionality—every call to start the profiler will start it, and the same goes for launch profiles if you've configured that. If you are interested in reducing the amount of profiles that run, you must take care to do it at the call sites.
 
 Continuous profiling has implications for your org's billing structure. This feature is only available for subscription plans that enrolled after June 5, 2024.
diff --git a/docs/product/explore/profiling/getting-started.mdx b/docs/product/explore/profiling/getting-started.mdx
@@ -35,6 +35,7 @@ Profiling depends on Sentry's performance monitoring product being enabled befor
 <Include name="feature-stage-beta.mdx" />
 
 - Mobile
+  - [Android](/platforms/android/profiling/#continuous-profiling)
   - [iOS and macOS](/platforms/apple/guides/ios/profiling/#continuous-profiling)
 - Standalone and server apps
   - [Node.js](/platforms/javascript/guides/node/profiling/#enable-continuous-profiling)
