diff --git a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx index 1b7026e1ce41c..42c67e3361069 100644 --- a/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/android/tracing/instrumentation/automatic-instrumentation.mdx @@ -129,7 +129,7 @@ The App Start Instrumentation provides insight into how long your application ta The SDK differentiates between a cold and a warm start, but doesn't track hot starts/resumes. - **Cold start**: A cold start refers to an app's starting from scratch: the system's process has not, until this start, created the app's process. Cold starts happen in cases such as your app's being launched for the first time since the device booted, or since the system killed the app. -- **Warm start**: A warm start encompasses some subset of the operations that take place during a cold start; at the same time, it represents more overhead than a hot start. For instance: The system evicts your app from memory, and then the user re-launches it. The process and the activity need to be restarted, but the task can benefit somewhat from the saved instance state bundle passed into `onCreate()`. +- **Warm start**: Any start that isn't cold. This includes background returns (the app was in the background and the user re-launches it), activity recreation (for example, the system evicts your app from memory and the process and activity need to be restarted), and late launches (the activity is created after the main looper goes idle). @@ -141,7 +141,7 @@ For example, Sentry measures the duration from process start, including the time The SDK sets the Span operation to `app.start.cold` for _Cold start_ and `app.start.warm` for _Warm start_. -The SDK uses the `SentryPerformanceProvider` (ContentProvider) creation time as the beginning of the app start and the first frame drawn as the end. +The SDK uses the process fork time as the beginning of the app start (API 24+), with a fallback to the `SentryPerformanceProvider` (ContentProvider) creation time on older API levels. The measurement ends when the first frame is drawn. 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..a2b9864137159 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,57 @@ 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** | Any start that isn't cold — includes background returns, activity recreation, and late launches | Anytime except 3 cases above | +| **Measurement start** | Process fork time (API 24+), with fallback to ContentProvider creation | 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, with standalone app starts, check `app.vitals.start.prewarmed` value and for legacy app starts check the reported 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. + + + +For headless app starts, the measurement end is determined by the earliest available signal: `Application.onCreate` completion (if instrumented via the Sentry Gradle plugin), `ApplicationStartInfo` timestamps (API 35+), or the SDK class load time as a last resort. + + + +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..8a781ac20a25f 100644 --- a/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/index.mdx +++ b/docs/product/dashboards/sentry-dashboards/mobile/mobile-vitals/index.mdx @@ -11,34 +11,33 @@ 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: - [Android](/platforms/android/tracing/instrumentation/automatic-instrumentation/#app-start-instrumentation) -- [Apple](/platforms/apple/guides/ios/tracing/instrumentation/automatic-instrumentation/#app-start-tracking) -- [Flutter](/platforms/dart/guides/flutter/tracing/instrumentation/automatic-instrumentation/#app-start-instrumentation) +- [Apple](/platforms/apple/guides/ios/tracing/instrumentation/automatic-instrumentation/#app-start-tracing) +- [Flutter](/platforms/dart/guides/flutter/integrations/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/)