Monitor app launch performance for iOS and Android in RUM

config/_default/menus/main.en.yaml

@@ -8103,51 +8103,56 @@ menu:
       parent: rum_mobile_android
       identifier: rum_mobile_android_crash
       weight: 102
+    - name: Monitoring App Launch
+      url: real_user_monitoring/application_monitoring/android/application_launch_monitoring
+      parent: rum_mobile_android
+      identifier: rum_mobile_android_application_launch_monitoring
+      weight: 103
     - name: Monitoring App Performance
       url: real_user_monitoring/application_monitoring/android/monitoring_app_performance
       parent: rum_mobile_android
       identifier: rum_mobile_android_monitoring_app_performance
-      weight: 103
+      weight: 104
     - name: Advanced Configuration
       url: real_user_monitoring/application_monitoring/android/advanced_configuration
       parent: rum_mobile_android
       identifier: rum_mobile_android_advanced_config
-      weight: 104
+      weight: 105
     - name: Data Collected
       url: real_user_monitoring/application_monitoring/android/data_collected
       parent: rum_mobile_android
       identifier: rum_mobile_android_data_collected
-      weight: 105
+      weight: 106
     - name: Mobile Vitals
       url: real_user_monitoring/application_monitoring/android/mobile_vitals
       parent: rum_mobile_android
       identifier: rum_mobile_android_mobile_vitals
-      weight: 106
+      weight: 107
     - name: Web View Tracking
       url: real_user_monitoring/application_monitoring/android/web_view_tracking
       parent: rum_mobile_android
       identifier: rum_mobile_android_web_view_tracking
-      weight: 107
+      weight: 108
     - name: Integrated Libraries
       url: real_user_monitoring/application_monitoring/android/integrated_libraries
       parent: rum_mobile_android
       identifier: rum_mobile_android_integrated_libraries
-      weight: 108
+      weight: 109
     - name: Jetpack Compose Instrumentation
       url: real_user_monitoring/application_monitoring/android/jetpack_compose_instrumentation
       parent: rum_mobile_android
       identifier: rum_mobile_android_jetpack_compose_instrumentation
-      weight: 109
+      weight: 110
     - name: Troubleshooting
       url: real_user_monitoring/application_monitoring/android/troubleshooting
       parent: rum_mobile_android
       identifier: rum_mobile_android_troubleshooting
-      weight: 110
+      weight: 111
     - name: SDK Performance Impact
       url: real_user_monitoring/application_monitoring/android/sdk_performance_impact
       parent: rum_mobile_android
       identifier: rum_mobile_android_performance_overhead
-      weight: 111
+      weight: 112
     - name: iOS and tvOS
       url: real_user_monitoring/application_monitoring/ios
       parent: application_monitoring
@@ -8163,51 +8168,56 @@ menu:
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_crash
       weight: 102
+    - name: Monitoring App Launch
+      url: real_user_monitoring/application_monitoring/ios/application_launch_monitoring
+      parent: rum_mobile_ios
+      identifier: rum_mobile_ios_application_launch_monitoring
+      weight: 103
     - name: Mobile App Performance
       url: real_user_monitoring/application_monitoring/ios/monitoring_app_performance
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_monitoring_app_performance
-      weight: 103
+      weight: 104
     - name: Advanced Configuration
       url: real_user_monitoring/application_monitoring/ios/advanced_configuration
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_advanced_config
-      weight: 104
+      weight: 105
     - name: Data Collected
       url: real_user_monitoring/application_monitoring/ios/data_collected
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_data_collected
-      weight: 105
+      weight: 106
     - name: Mobile Vitals
       url: real_user_monitoring/application_monitoring/ios/mobile_vitals?tab=ios
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_mobile_vitals
-      weight: 106
+      weight: 107
     - name: Web View Tracking
       url: real_user_monitoring/application_monitoring/ios/web_view_tracking?tab=ios
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_web_view_tracking
-      weight: 107
+      weight: 108
     - name: Integrated Libraries
       url: real_user_monitoring/application_monitoring/ios/integrated_libraries
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_integrated_libraries
-      weight: 108
+      weight: 109
     - name: Troubleshooting
       url: real_user_monitoring/application_monitoring/ios/troubleshooting
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_troubleshooting
-      weight: 109
+      weight: 110
     - name: Supported Versions
       url: real_user_monitoring/application_monitoring/ios/supported_versions
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_supported_versions
-      weight: 110
+      weight: 111
     - name: SDK Performance Impact
       url: real_user_monitoring/application_monitoring/ios/sdk_performance_impact
       parent: rum_mobile_ios
       identifier: rum_mobile_ios_performance_overhead
-      weight: 111
+      weight: 112
     - name: Flutter
       url: real_user_monitoring/application_monitoring/flutter
       parent: application_monitoring

content/en/real_user_monitoring/application_monitoring/android/_index.md

@@ -27,6 +27,7 @@ To get started with RUM for Android, create an application and configure the And
 {{< whatsnext desc="This section includes the following topics:">}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/android/setup">}}<u>Setup</u>: Learn how to set up the Android SDK, track background events, and send data when devices are offline.{{< /nextlink >}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/android/error_tracking">}}<u>Crash Reporting</u>: Add ANR detection and crash reporting, get deobfuscated stack traces, then test your implementation.{{< /nextlink >}}
+  {{< nextlink href="/real_user_monitoring/application_monitoring/android/application_launch_monitoring">}}<u>Application Launch Monitoring</u>: Measure Android mobile application launch performance, including the time to initial display and time to full display.{{< /nextlink >}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/android/monitoring_app_performance">}}<u>Monitoring App Performance</u>: Monitor view timings to understand your app's performance from a user's perspective. {{< /nextlink >}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/android/advanced_configuration">}}<u>Advanced Configuration</u>: Enrich user sessions, manage events and data, track custom global attributes and widgets, review initialization parameters, modify or drop RUM events, and more.{{< /nextlink >}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/android/mobile_vitals">}}<u>Data Collected</u>: Review data that the Android SDK collects.{{< /nextlink >}}

content/en/real_user_monitoring/application_monitoring/android/application_launch_monitoring.md

@@ -0,0 +1,124 @@
+---
+title: Android Mobile App Launch Monitoring
+description: "Measure Android mobile application launch performance, including the time to initial display and time to full display."
+aliases:
+- /real_user_monitoring/android/application_launch_monitoring/
+- /real_user_monitoring/mobile_and_tv_monitoring/application_launch_monitoring/android
+- /real_user_monitoring/mobile_and_tv_monitoring/android/application_launch_monitoring
+further_reading:
+- link: https://github.com/DataDog/dd-sdk-android
+  tag: "Source Code"
+  text: Source code for dd-sdk-android
+- link: /real_user_monitoring
+  tag: Documentation
+  text: Explore Datadog RUM
+---
+
+<div class="alert alert-danger">
+  The <code>application_start</code> action is no longer collected starting from Android SDK version 3.5.0. The <code>rum.measure.app.startup_time metric</code> is marked as deprecated but continues to report data from devices running app versions that use older SDK versions.
+</div>
+
+## Overview
+
+Application launch monitoring helps you understand how fast your Android app becomes usable after a user taps the app icon. Use it to identify slow startup times, track performance regressions, and optimize the user’s first impression of your app.
+
+With this feature, you can:
+- Measure time to initial display (TTID) and time to full display (TTFD) for cold and warm starts
+- View launch performance trends in the RUM Summary and Mobile Performance Dashboard
+- Drill into individual launch events to diagnose bottlenecks
+
+## How it works
+
+During initialization, the RUM Android SDK creates a view called `ApplicationLaunch`. This view’s start time matches the start of the Android process. The `ApplicationLaunch` view includes any logs, actions, and resources created before your first call to `startView`. 
+
+### Time to initial display and time to full display
+
+Starting from Android SDK version 3.5.0, the time to initial display (TTID) and time to full display (TTFD) will be collected during the application launch period.
+
+| Measurement       | Summary  | Details                                                                                                                |
+|----------------|----------|----------------------------------------------------------------------------------------------------------------------------------|
+| [Time to initial display][1] | The time it takes to display the first frame of the app's UI. | The time taken for an app to produce its first frame, including process initialization during a cold start, activity creation during a cold or warm start, and displaying the first frame. |
+| [Time to full display][2] | The time it takes for an app to become interactive for the user. | The time taken to display the first frame of the app's UI, as well as the content that loads asynchronously after the initial frame is displayed. |
+
+Each time to initial display and time to full display is categorized by launch type:
+- [Cold start][3]: The application is launched from scratch. Cold starts happen when the application is launched for the first time since device boot or since the system terminated the process of the application.
+- [Warm start][4]: The application is launched using a subset of the operations that take place during a cold start. Warm starts result from situations such as a user backing out of the application or re-launching the application. Warm starts can also result from the user launching the `Activity` when the OS-process already exists, such as the arrival of a silent push or `WorkManager` job execution."
+
+### Measuring the time to initial display
+The Android SDK automatically measures the TTID. The TTID can be optionally profiled using the Android Mobile Profiler.
+
+### Measuring the time to full display
+The time to full display is manually defined using the `GlobalRumMonitor.get().reportAppFullyDisplayed` API in the Android SDK based on the application’s specific definition of “fully drawn.” 
+
+Below is an example where time to full display is determined when home activity is fully loaded.
+
+{{< tabs >}}
+{{% tab "Kotlin" %}}
+
+```kotlin
+class SampleApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        val configuration = Configuration.Builder(
+            clientToken = "<CLIENT_TOKEN>",
+            env = "<ENV_NAME>",
+            variant = "<APP_VARIANT_NAME>"
+        ).build()
+
+        Datadog.initialize(this, configuration, trackingConsent)
+    }
+}
+```
+{{% /tab %}}
+{{< /tabs >}}
+
+If you use reportFullyDrawn to identify the moment of full display, you can use getFullyDrawnReporter to subscribe to `reportFullyDrawn` and call `RumMonitor.reportFullyDrawn`. If you do not use reportFullyDrawn, you can still call `RumMonitor.reportFullyDrawn`, but it will make sense only for cold and warm starts, rather than hot starts.
+
+<div class="alert alert-danger">
+  If the time to full display is not defined, the Android SDK only collects the TTID.
+</div>
+
+### RUM summary
+
+The TTID and TTFD are presented in the RUM Summary under Mobile Performance. The standalone Mobile Performance Dashboard also contains distribution visuals for TTID and TTFD. 
+
+  {{< img src="real_user_monitoring/android/android-rum-summary-app-launch.png" alt="Android RUM Summary" style="width:90%;">}}
+
+### Vital events
+
+The time to initial display and time to full display are presented as vital events in the RUM session. They are also found under the first view after the `ApplicationLaunch` view. TTID and TTFD will be captured if the user launched the application in the session. Neither the TTID nor the TTFD will appear if the user did not launch the application during the session. 
+
+  {{< img src="real_user_monitoring/android/android-app-launch-session.png" alt="Android session side panel" style="width:90%;">}}
+
+
+The TTID and TTFD can be queried in the RUM Sessions Explorer using the following attributes on the vital event type:
+- `@vital.type: app_launch`
+- `@vital.name: time_to_initial_display` or `@vital.name: time_to_full_display`
+
+Each TTID and TTFD side panel contains a distribution visualization, an indication of whether the launch was cold or warm, and an event waterfall. 
+
+  {{< img src="real_user_monitoring/android/android-ttid-vital.png" alt="Time to initial display vital event" style="width:90%;">}}
+
+If Android profiling is enabled and the session is sampled, the time to initial display may include profiling data.
+
+### Metrics
+The time to initial display and time to full display are calculated as metrics:
+- `rum.measure.app.startup_to_initial_display`, which represents the time to initial display 
+- `rum.measure.app.startup_to_full_display`, which represents the time to full display
+
+These metrics contain the `@vital.startup_type` attribute to specify the launch type for accurate monitoring.
+
+<div class="alert alert-danger">
+  The <code>rum.measure.app.startup_to_full_display</code> metric will not be calculated if the time to full display is not defined. 
+</div>
+
+## Further Reading
+
+{{< partial name="whats-next/whats-next.html" >}}
+
+[1]: https://developer.android.com/topic/performance/vitals/launch-time#time-initial
+[2]: https://developer.android.com/topic/performance/vitals/launch-time#time-full 
+[3]: https://developer.android.com/topic/performance/vitals/launch-time#cold 
+[4]: https://developer.android.com/topic/performance/vitals/launch-time#warm
+[5]: https://developer.android.com/reference/android/app/Activity#reportFullyDrawn()
+[6]: https://developer.android.com/reference/androidx/activity/ComponentActivity#getFullyDrawnReporter%28%29

content/en/real_user_monitoring/application_monitoring/android/data_collected.md

@@ -35,15 +35,6 @@ The following diagram illustrates the RUM event hierarchy:
 
 {{< img src="real_user_monitoring/data_collected/event-hierarchy.png" alt="RUM Event hierarchy" style="width:50%;" >}}
 
-## Application launch
-
-During initialization, the RUM Android SDK creates a view called "ApplicationLaunch". This view's start time matches the start of the Android process, and can be used to track your application launch time.
-
-The `ApplicationLaunch` view includes any logs, actions, and resources created before your first call to `startView`. Use the duration of this view to determine time to first view. This view has an action, `application_start`, with a duration that depends on Android version:
-
-- In *Android 7.0* and above, this view/action captures the period before any application code is executed (right before `Application.onCreate`) and when the first RUM event is recorded.
-- In versions before *Android 7.0*, the view/action captures the period between the `RumFeature` class loads and when the first RUM event is recorded.
-
 ## Views instrumentation versus app lifecycle
 
 The Android RUM SDK offers various strategies to [automatically track views][2] like Activities, Fragments, or Navigation destinations. You can also track views manually by directly calling the RUM APIs. The precise moment a view starts or stops depends on the chosen tracking strategy or manual instrumentation:

content/en/real_user_monitoring/application_monitoring/ios/_index.md

@@ -26,6 +26,7 @@ To get started with RUM for iOS, create an application and configure the iOS SDK
 {{< whatsnext desc="This section includes the following topics:">}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/ios/setup">}}<u>Setup</u>: Learn how to set up the iOS SDK, track background events, and send data when devices are offline.{{< /nextlink >}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/ios/error_tracking">}}<u>Crash Reporting</u>: Add crash reporting, get deobfuscated stack traces, then test your implementation.{{< /nextlink >}}
+   {{< nextlink href="/real_user_monitoring/application_monitoring/ios/application_launch_monitoring">}}<u>Application Launch Monitoring</u>: Measure iOS mobile application launch performance, including the time to initial display and time to full display.{{< /nextlink >}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/ios/monitoring_app_performance">}}<u>Monitoring App Performance</u>: Monitor view timings to understand your app's performance from a user's perspective. {{< /nextlink >}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/ios/advanced_configuration">}}<u>Advanced Configuration</u>: Enrich user sessions, manage events and data, track custom global attributes, review initialization parameters, modify or drop RUM events, and more.{{< /nextlink >}}
   {{< nextlink href="/real_user_monitoring/application_monitoring/ios/mobile_vitals">}}<u>Data Collected</u>: Review data that the RUM iOS SDK collects.{{< /nextlink >}}