diff --git a/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/app-starts.mdx b/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/app-starts.mdx index c45e95d189dc6..906a080013c70 100644 --- a/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/app-starts.mdx +++ b/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/app-starts.mdx @@ -59,9 +59,9 @@ By default, the **App Starts** dashboard displays metrics for the two releases w The charts display the following metrics (using cold starts as an example): - Average Cold Start - - The overall time it takes your application to start, compared by release. + - The overall time it takes your application to start, compared by release. - Cold Start Device Distribution - - The average cold start time grouped by [device class](/concepts/search/searchable-properties/#device-classification) (high, medium, low, or unknown). + - The average cold start time grouped by [device class](/concepts/search/searchable-properties/#device-classification) (high, medium, low, or unknown). **Reasons Why You Might Not Be Seeing Any Data:** @@ -76,16 +76,51 @@ Clicking the "By Event" toggle in the top right corner of this table will show y The following table describes the span operations that are surfaced in the spans table: -| Platform | Span Operations | -| --- | --- | -| Common | | -| [iOS](/platforms/apple/guides/ios/tracing/instrumentation/automatic-instrumentation/#app-start-tracing) | | -| Android | | +| Platform | Span Operations | +| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Common | | +| [iOS](/platforms/apple/guides/ios/tracing/instrumentation/automatic-instrumentation/#app-start-tracing) | | +| Android | | + +## Cold and Warm Starts + +Both Android and iOS distinguish between cold and warm starts, but the exact definitions and measurement approaches differ between platforms: + +| | Android | iOS | +| --- | --- | --- | +| **Cold start** | Process doesn't exist; app starts from scratch | First launch ever, after a reboot or update | +| **Warm start** | Process existed but Activity is recreated | Anytime except 3 cases above | +| **Measurement start** | ContentProvider creation (`SentryPerformanceProvider`) | Process creation | +| **Measurement end** | First frame drawn | | +| **Recommended threshold** | Cold < 5s, Warm < 2s ([Google Play Console](https://developer.android.com/topic/performance/vitals/launch-time#av)) | < 400ms for first frame ([Apple](https://developer.apple.com/videos/play/wwdc2019/423/)) | +| **Prewarming** | N/A | iOS 15+ may prewarm processes, resulting in additional start types (`cold.prewarmed`, `warm.prewarmed`) | + +For full details, see the [Android app start](/platforms/android/tracing/instrumentation/automatic-instrumentation/#app-start-instrumentation) and [iOS app start](/platforms/apple/tracing/instrumentation/automatic-instrumentation/#app-start-tracing) SDK documentation. + +## Headless App Starts + + + +Headless app start tracking is only available on Android. It is **not supported** on iOS or hybrid SDKs (React Native, Flutter). + + + +A headless app start occurs when your Android application's process is created without launching a visible `Activity`. This can happen when the app is started by a broadcast receiver, a content provider, or a background service — the process initializes but no UI is displayed to the user. + +By default, Sentry only tracks app starts that result in a foreground `Activity` being displayed. With headless app start tracking, Sentry can also capture these non-UI process launches, giving you visibility into background initialization performance. + +Headless app start tracking requires [standalone app start tracing](/platforms/android/tracing/instrumentation/automatic-instrumentation/#app-start-instrumentation) to be enabled in your Android SDK configuration: + +```xml {filename:AndroidManifest.xml} + + + +``` ## Span Detail View ![Example of Span Detail View =900x](./img/mobile-span-details.png) -Clicking on a span description opens up the Traces page, where you can see sampled spans. +Clicking on a span description opens up the Traces page, where you can see sampled spans. In the table, you'll see a list of sampled spans. Click into one to get a waterfall view of the span. diff --git a/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/img/mobile-warm-start.png b/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/img/mobile-warm-start.png index d98d9e6d411bf..6bc608f119a06 100644 Binary files a/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/img/mobile-warm-start.png and b/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/img/mobile-warm-start.png differ diff --git a/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/index.mdx b/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/index.mdx index 19142cb608451..76820e08c85e0 100644 --- a/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/index.mdx +++ b/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/index.mdx @@ -11,7 +11,7 @@ The Mobile Vitals dashboard, found in [Sentry Dashboards](https://sentry.io/orgr ## App Start -App start metrics track how long your mobile application takes to launch. For this, Sentry measures [_cold starts_]( /concepts/search/searchable-properties/events/#measurementsapp_start_cold) and [_warm starts_](/concepts/search/searchable-properties/events/#measurementsapp_start_warm). +App start metrics track how long your mobile application takes to launch. For this, Sentry measures [_cold starts_](/concepts/search/searchable-properties/events/#measurementsapp_start_cold) and [_warm starts_](/concepts/search/searchable-properties/events/#measurementsapp_start_warm). The definitions of cold start and warm start change slightly depending on the operating system. On iOS, Apple recommends your app take at most 400ms to render the first frame. On Android, the [Google Play console](https://developer.android.com/topic/performance/vitals/launch-time#av) warns you when a cold start takes longer than five seconds or a warm start longer than two seconds. For definitions by operating system, check out the corresponding SDK docs: @@ -20,25 +20,24 @@ The definitions of cold start and warm start change slightly depending on the op - [Flutter](/platforms/dart/guides/flutter/tracing/instrumentation/automatic-instrumentation/#app-start-instrumentation) - [React Native](/platforms/react-native/tracing/instrumentation/automatic-instrumentation/#app-start-instrumentation) +On Android, Sentry can also track [headless app starts](/product/dashboards/sentry-dashboards/mobile/mobile-vitals/app-starts/#headless-app-starts) (process launches that occur without a visible Activity, such as those triggered by a broadcast receiver or background service). Headless app start tracking is not available on iOS or hybrid SDKs. + Sentry's App Start instrumentation aims to be as comprehensive and representative of the user experience as possible, and adheres to guidelines by the platform vendors. For this reason, App Starts reported by Sentry might be longer than what you see in other tools. Read more on the [Apple App Start docs](/platforms/apple/guides/ios/tracing/instrumentation/automatic-instrumentation/#app-start-tracing) and [Android App Start docs](/platforms/android/tracing/instrumentation/automatic-instrumentation/#app-start-instrumentation). - In the example below, the detail view of a trace displays the warm start measurement in the right sidebar. ![The event detail of a trace with a warm start measurement. =800x](./img/mobile-warm-start.png) -While the SDKs differentiate between cold and warm starts, they don't track hot starts or resumes. To get more insight into your cold and warm start metrics, you can use the [App Starts](/product/dashboards/sentry-dashboards/mobile/mobile-vitals/app-starts/) feature. - ## Performance Score Sentry categorizes average app start durations as follows: -| Metric | Good | Meh | Poor | -| --- | --- | --- | --- | +| Metric | Good | Meh | Poor | +| ---------------------- | ------------ | ----------------- | --------------- | | Average Cold App Start | less than 3s | between 3s and 5s | greater than 5s | | Average Warm App Start | less than 1s | between 1s and 2s | greater than 2s | @@ -68,9 +67,10 @@ You can track slow and frozen frames for: ## Frames Delay -Frames Delay is the user-perceived total delayed duration of rendered frames. For example, at a refresh rate of 60fps, if a two frame renders takes 20ms each, the frame delay is 8ms (2 * (20ms - 16ms) = 8ms). +Frames Delay is the user-perceived total delayed duration of rendered frames. For example, at a refresh rate of 60fps, if a two frame renders takes 20ms each, the frame delay is 8ms (2 \* (20ms - 16ms) = 8ms). You can track frames delay on the following platforms: + - [Android](/platforms/android/tracing/instrumentation/perf-v2/#frames-delay) - [Apple, as part of slow and frozen frames](/platforms/apple/guides/ios/tracing/instrumentation/automatic-instrumentation/#slow-and-frozen-frames) - [Flutter](/platforms/dart/guides/flutter/integrations/slow-and-frozen-frames-instrumentation/)