Add Android App Start Profiling (#8899)

* added enable-app-start manifest option
* added small description of App Start Profiling
* mention TransactionContext.isForNextAppStart in sampler functions
* added profiling options in Basic Options

Author: stefanosiano

src/platform-includes/performance/traces-sampler-as-sampler/android.mdx

@@ -10,6 +10,10 @@ SentryAndroid.init(this, options -> {
   options.setTracesSampleRate(1.0);
   // OR: Determine traces sample rate based on the sampling context
   options.setTracesSampler(context -> {
+    if (context.getTransactionContext().isForNextAppStart()) {
+      // These refer to app start (if app start profiling is enabled), and are important - take a big sample
+      return 0.7;
+    }
     CustomSamplingContext ctx = context.getCustomSamplingContext();
     if (ctx != null) {
       if ("LoginActivity".equals(ctx.get("ActivityName"))) {
@@ -38,6 +42,10 @@ import io.sentry.SentryOptions.TracesSamplerCallback
 
 SentryAndroid.init(this) { options ->
   options.tracesSampler = TracesSamplerCallback { context ->
+    if (context.transactionContext.isForNextAppStart) {
+      // These refer to app start (if app start profiling is enabled), and are important - take a big sample
+      return@TracesSamplerCallback 0.7
+    }
     val ctx = context.customSamplingContext
     if (ctx != null) {
       when (ctx.get("ActivityName")) {

src/platforms/android/configuration/options.mdx

@@ -307,3 +307,29 @@ If <PlatformIdentifier name="trace-propagation-targets" /> is not provided, trac
 Set this boolean to `false` to disable tracing for `OPTIONS` requests. This options default value will likely be changed in the next major version, meaning you will have to set it to `true` if you want to keep tracing `OPTIONS` requests.
 
 </ConfigKey>
+
+## Profiling Options
+
+<ConfigKey name="enable-tracing">
+
+A boolean value, if true, transactions and trace data will be generated and captured. This will set the `traces-sample-rate` to the recommended default of 1.0 if `traces-sample-rate` is not defined. Note that `traces-sample-rate` and `traces-sampler` take precedence over this option.
+
+</ConfigKey>
+
+<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.
+
+</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.
+
+</ConfigKey>
+
+<ConfigKey name="enable-app-start-profiling">
+
+A boolean value, if true, the startup process, including ContentProviders, Application and first Activity creation, will be profiled. Note that `profiles-sample-rate` or `profiles-sampler` must be defined.
+
+</ConfigKey>

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

@@ -48,6 +48,8 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp
   <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 app start profiling -->
+  <meta-data android:name="io.sentry.traces.profiling.enable-app-start" android:value="true" />
 </application>
 ```
 

src/platforms/android/profiling/index.mdx

@@ -30,6 +30,7 @@ By default, some transactions will be created automatically for common operation
 <Note>
 
 Android profiling is available starting in SDK version `6.16.0`.
+App start profiling is available starting in SDK version `7.3.0`.
 
 </Note>
 
@@ -42,6 +43,7 @@ In `AndroidManifest.xml`:
     <meta-data android:name="io.sentry.dsn" android:value="___PUBLIC_DSN___" />
     <meta-data android:name="io.sentry.traces.sample-rate" android:value="1.0" />
     <meta-data android:name="io.sentry.traces.profiling.sample-rate" android:value="1.0" />
+    <meta-data android:name="io.sentry.traces.profiling.enable-app-start" android:value="true" />
 </application>
 ```
 
@@ -50,3 +52,17 @@ In `AndroidManifest.xml`:
 The `io.sentry.traces.profiling.sample-rate` setting is _relative_ to the `io.sentry.traces.sample-rate` setting.
 
 </Note>
+
+## App Start Profiling
+
+When app start profiling is enabled, the whole app start process is profiled.  
+This includes all methods from any `ContentProvider`, the `Application` class, and the first Activity, until the <PlatformLink to="/performance/instrumentation/automatic-instrumentation/">first automatic Activity transaction</PlatformLink> is finished.  
+App start profiling can be enabled with the manifest option `io.sentry.traces.profiling.enable-app-start` as shown above, and it will respect the `io.sentry.traces.sample-rate` and the `io.sentry.traces.profiling.sample-rate`.  
+If you prefer to use a <PlatformLink to="/configuration/sampling/#setting-a-sampling-function">sampling function</PlatformLink>, the SDK sets the `isForNextAppStart` field on the `TransactionContext` to specify it will be used for the next app start profiling.
+
+<Note>
+
+The SDK won't run app start profiling the very first time the app runs, as the SDK won't have read the options by the time the profile should run.  
+The SDK will set the `isForNextAppStart` flag in `TransactionContext` if app start profiling is enabled.
+
+</Note>