feat(apple): Add docs for pre-warmed app starts (#5762)

Add docs for the experimental feature enablePreWarmedAppStartTracking,
which will be released with
getsentry/sentry-cocoa#1969.

Co-authored-by: Liza Mock <[email protected]>
Co-authored-by: Isabel <[email protected]>

Author: 3 people

src/platform-includes/getting-started-config/apple.mdx

@@ -80,6 +80,7 @@ SentrySDK.start { options in
 
     // Enable all experimental features
     options.enableUserInteractionTracing = true
+    options.enablePreWarmedAppStartTracking = true
     options.attachScreenshot = true
     options.attachViewHierarchy = true
 }
@@ -92,6 +93,7 @@ SentrySDK.start { options in
 
     // Enable all experimental features
     options.enableUserInteractionTracing = YES;
+    options.enablePreWarmedAppStartTracking = YES;
     options.attachScreenshot = YES;
     options.attachViewHierarchy = YES;
 }];

src/platforms/apple/common/performance/instrumentation/automatic-instrumentation.mdx

@@ -55,12 +55,6 @@ This feature is available for iOS, tvOS, and Mac Catalyst.
 App Start Tracking is enabled by default once you <PlatformLink to="/performance/">set up performance monitoring</PlatformLink>. This feature provides insight into how long your application takes to launch. It adds spans for different phases, from the application launch to the first auto-generated UI transaction.
 To enable this feature, enable `AutoUIPerformanceTracking`.
 
-<Alert level="info" title="Important">
-
-Starting with iOS 15, the system might [pre-warm](https://developer.apple.com/documentation/uikit/app_and_environment/responding_to_the_launch_of_your_app/about_the_app_launch_sequence#3894431) your app by creating the process before the user opens it. In such cases, we can't reliably measure the app start, so we drop it as of [sentry-cocoa 7.18.0](https://github.com/getsentry/sentry-cocoa/releases/tag/7.18.0). We are working on a fix for this. Follow the [GitHub issue](https://github.com/getsentry/sentry-cocoa/issues/1897) for more details.
-
-</Alert>
-
 The SDK differentiates between a cold and a warm start, but doesn't track hot starts/resumes.
 
 * __Cold start__: App launched for the first time, after a reboot or update. The app is not in memory and no process exists.
@@ -75,6 +69,40 @@ The SDK uses the process start time as the beginning of the app start and the [`
 
 Cold and warm start are Mobile Vitals, which you can learn about in the [full documentation](/product/performance/mobile-vitals).
 
+### Prewarmed App Start Tracking
+
+Starting with iOS 15, the system might [prewarm](https://developer.apple.com/documentation/uikit/app_and_environment/responding_to_the_launch_of_your_app/about_the_app_launch_sequence#3894431) your app by creating the process before the user opens it. In these cases, we won’t be able to reliably measure the app start. However, with [sentry-cocoa 7.31.0](https://github.com/getsentry/sentry-cocoa/releases/tag/7.31.0), we’ve introduced an `enablePreWarmedAppStartTracking` feature (still in its experimental phase), which allows us to collect prewarmed app starts.
+
+Once enabled, the SDK drops the first app start span if prewarming pauses. This approach shortens the app start duration, but it accurately represents the span of time from when a user clicks the app icon to when the app is responsive.
+With this feature, the SDK differentiates between four different app start types:
+
+* __Non-prewarmed cold start__ (See _cold start_  definition above.)
+* __Non-prewarmed warm start__ (See _warm start_  definition above.)
+* __Prewarmed cold start__
+* __Prewarmed warm start__
+
+You can filter for different app start types in [Discover](/product/discover-queries/) with `app_start_type:cold.prewarmed`, `app_start_type:warm.prewarmed`, `app_start_type:cold`, and `app_start_type:warm`.
+
+To enable prewarmed app start tracking:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.enablePreWarmedAppStartTracking = true
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.enablePreWarmedAppStartTracking = YES;
+}];
+```
+
 ## Slow and Frozen Frames
 
 This feature is available for iOS, tvOS, and Mac Catalyst.

src/wizard/apple/ios.md

@@ -118,6 +118,7 @@ SentrySDK.start { options in
 
     // Enable all experimental features
     options.enableUserInteractionTracing = true
+    options.enablePreWarmedAppStartTracking = true
     options.attachScreenshot = true
     options.attachViewHierarchy = true
 }