feat: Standalone app start tracing

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Add standalone app start tracing as an experimental option (#7660), enable it via `options.experimental.enableStandaloneAppStartTracing = true`
+
 ## 9.7.0
 
 ### Features

Sources/Sentry/SentryAppStartMeasurementProvider.m

@@ -94,6 +94,13 @@ + (nullable SentryAppStartMeasurement *)appStartMeasurementForOperation:(NSStrin
     return measurement;
 }
 
++ (void)markAsRead
+{
+    @synchronized(appStartMeasurementLock) {
+        appStartMeasurementRead = YES;
+    }
+}
+
 + (void)reset
 {
     @synchronized(appStartMeasurementLock) {

Sources/Sentry/SentryBuildAppStartSpans.m

@@ -1,15 +1,19 @@
 #import "SentryAppStartMeasurement.h"
+#import "SentryLogC.h"
 #import "SentrySpanContext+Private.h"
 #import "SentrySpanId.h"
 #import "SentrySpanInternal.h"
+#import "SentrySpanOperation.h"
 #import "SentrySwift.h"
 #import "SentryTraceOrigin.h"
 #import "SentryTracer.h"
 #import <SentryBuildAppStartSpans.h>
 
 #if SENTRY_HAS_UIKIT
 
-id<SentrySpan>
+#    pragma mark - Private
+
+static id<SentrySpan>
 sentryBuildAppStartSpan(
     SentryTracer *tracer, SentrySpanId *parentId, NSString *operation, NSString *description)
 {
@@ -22,14 +26,19 @@
                                             origin:SentryTraceOriginAutoAppStart
                                            sampled:tracer.sampled];
 
+    // Pass nil for the framesTracker because app start spans are created during launch,
+    // before the frames tracker is available.
     return [[SentrySpanInternal alloc] initWithTracer:tracer context:context framesTracker:nil];
 }
 
-NSArray<id<SentrySpan>> *
-sentryBuildAppStartSpans(
-    SentryTracer *tracer, SentryAppStartMeasurement *_Nullable appStartMeasurement)
+/**
+ * Internal helper that builds the app start child spans. When @c isStandalone is @c YES the
+ * intermediate grouping span is omitted and children are parented directly to the tracer.
+ */
+static NSArray<id<SentrySpan>> *
+sentryBuildAppStartSpansInternal(SentryTracer *tracer,
+    SentryAppStartMeasurement *_Nullable appStartMeasurement, BOOL isStandalone)
 {
-
     if (appStartMeasurement == nil) {
         return @[];
     }
@@ -39,14 +48,15 @@
 
     switch (appStartMeasurement.type) {
     case SentryAppStartTypeCold:
-        operation = @"app.start.cold";
+        operation = SentrySpanOperationAppStartCold;
         type = @"Cold Start";
         break;
     case SentryAppStartTypeWarm:
-        operation = @"app.start.warm";
+        operation = SentrySpanOperationAppStartWarm;
         type = @"Warm Start";
         break;
     default:
+        SENTRY_LOG_ERROR(@"Unknown app start type, can't build app start spans");
         return @[];
     }
 
@@ -55,45 +65,67 @@
     NSDate *appStartEndTimestamp = [appStartMeasurement.appStartTimestamp
         dateByAddingTimeInterval:appStartMeasurement.duration];
 
-    id<SentrySpan> appStartSpan = sentryBuildAppStartSpan(tracer, tracer.spanId, operation, type);
-    [appStartSpan setStartTimestamp:appStartMeasurement.appStartTimestamp];
-    [appStartSpan setTimestamp:appStartEndTimestamp];
-
-    [appStartSpans addObject:appStartSpan];
+    SentrySpanId *appStartSpanParentId;
+    if (isStandalone) {
+        appStartSpanParentId = tracer.spanId;
+    } else {
+        id<SentrySpan> appStartSpan
+            = sentryBuildAppStartSpan(tracer, tracer.spanId, operation, type);
+        [appStartSpan setStartTimestamp:appStartMeasurement.appStartTimestamp];
+        [appStartSpan setTimestamp:appStartEndTimestamp];
+        [appStartSpans addObject:appStartSpan];
+        appStartSpanParentId = appStartSpan.spanId;
+    }
 
     if (!appStartMeasurement.isPreWarmed) {
         id<SentrySpan> premainSpan
-            = sentryBuildAppStartSpan(tracer, appStartSpan.spanId, operation, @"Pre Runtime Init");
+            = sentryBuildAppStartSpan(tracer, appStartSpanParentId, operation, @"Pre Runtime Init");
         [premainSpan setStartTimestamp:appStartMeasurement.appStartTimestamp];
         [premainSpan setTimestamp:appStartMeasurement.runtimeInitTimestamp];
         [appStartSpans addObject:premainSpan];
 
         id<SentrySpan> runtimeInitSpan = sentryBuildAppStartSpan(
-            tracer, appStartSpan.spanId, operation, @"Runtime Init to Pre Main Initializers");
+            tracer, appStartSpanParentId, operation, @"Runtime Init to Pre Main Initializers");
         [runtimeInitSpan setStartTimestamp:appStartMeasurement.runtimeInitTimestamp];
         [runtimeInitSpan setTimestamp:appStartMeasurement.moduleInitializationTimestamp];
         [appStartSpans addObject:runtimeInitSpan];
     }
 
     id<SentrySpan> appInitSpan
-        = sentryBuildAppStartSpan(tracer, appStartSpan.spanId, operation, @"UIKit Init");
+        = sentryBuildAppStartSpan(tracer, appStartSpanParentId, operation, @"UIKit Init");
     [appInitSpan setStartTimestamp:appStartMeasurement.moduleInitializationTimestamp];
     [appInitSpan setTimestamp:appStartMeasurement.sdkStartTimestamp];
     [appStartSpans addObject:appInitSpan];
 
     id<SentrySpan> didFinishLaunching
-        = sentryBuildAppStartSpan(tracer, appStartSpan.spanId, operation, @"Application Init");
+        = sentryBuildAppStartSpan(tracer, appStartSpanParentId, operation, @"Application Init");
     [didFinishLaunching setStartTimestamp:appStartMeasurement.sdkStartTimestamp];
     [didFinishLaunching setTimestamp:appStartMeasurement.didFinishLaunchingTimestamp];
     [appStartSpans addObject:didFinishLaunching];
 
     id<SentrySpan> frameRenderSpan
-        = sentryBuildAppStartSpan(tracer, appStartSpan.spanId, operation, @"Initial Frame Render");
+        = sentryBuildAppStartSpan(tracer, appStartSpanParentId, operation, @"Initial Frame Render");
     [frameRenderSpan setStartTimestamp:appStartMeasurement.didFinishLaunchingTimestamp];
     [frameRenderSpan setTimestamp:appStartEndTimestamp];
     [appStartSpans addObject:frameRenderSpan];
 
     return appStartSpans;
 }
 
+#    pragma mark - Public
+
+NSArray<id<SentrySpan>> *
+sentryBuildAppStartSpans(
+    SentryTracer *tracer, SentryAppStartMeasurement *_Nullable appStartMeasurement)
+{
+    return sentryBuildAppStartSpansInternal(tracer, appStartMeasurement, NO);
+}
+
+NSArray<id<SentrySpan>> *
+sentryBuildStandaloneAppStartSpans(
+    SentryTracer *tracer, SentryAppStartMeasurement *_Nullable appStartMeasurement)
+{
+    return sentryBuildAppStartSpansInternal(tracer, appStartMeasurement, YES);
+}
+
 #endif // SENTRY_HAS_UIKIT

Sources/Sentry/SentrySpanOperation.m

@@ -15,6 +15,9 @@
 
 NSString *const SentrySpanOperationUiAction = @"ui.action";
 NSString *const SentrySpanOperationUiActionClick = @"ui.action.click";
+NSString *const SentrySpanOperationAppStartCold = @"app.start.cold";
+NSString *const SentrySpanOperationAppStartWarm = @"app.start.warm";
+
 NSString *const SentrySpanOperationUiLoad = @"ui.load";
 NSString *const SentrySpanOperationUiLoadInitialDisplay = @"ui.load.initial_display";
 NSString *const SentrySpanOperationUiLoadFullDisplay = @"ui.load.full_display";

Sources/Sentry/SentryTracer.m

@@ -596,9 +596,22 @@ - (BOOL)finishTracer:(SentrySpanStatus)unfinishedSpansFinishStatus shouldCleanUp
         [super finishWithStatus:_finishStatus];
     }
 #if SENTRY_HAS_UIKIT
-    appStartMeasurement =
-        [SentryAppStartMeasurementProvider appStartMeasurementForOperation:self.operation
-                                                            startTimestamp:self.startTimestamp];
+    // Standalone app start transactions carry their measurement directly in the configuration,
+    // bypassing the global static in SentryAppStartMeasurementProvider. The main advantage is
+    // avoiding a race condition between the app start tracker producing the measurement and
+    // the first UIViewController transaction consuming it. We don't change the existing
+    // UIViewController/AppStart path below because it's bulletproof and we'll likely remove
+    // it once standalone app start tracing is stable.
+    if ([self isStandaloneAppStartTransaction] && _configuration.appStartMeasurement != nil) {
+        appStartMeasurement = _configuration.appStartMeasurement;
+        // Safeguard: this shouldn't normally happen, but mark as read so no UIViewController
+        // transaction picks up the global static too.
+        [SentryAppStartMeasurementProvider markAsRead];
+    } else {
+        appStartMeasurement =
+            [SentryAppStartMeasurementProvider appStartMeasurementForOperation:self.operation
+                                                                startTimestamp:self.startTimestamp];
+    }
 
     if (appStartMeasurement != nil) {
         [self updateStartTime:appStartMeasurement.appStartTimestamp];
@@ -706,7 +719,9 @@ - (SentryTransaction *)toTransaction
 #if SENTRY_HAS_UIKIT
     [self addFrameStatistics];
 
-    NSArray<id<SentrySpan>> *appStartSpans = sentryBuildAppStartSpans(self, appStartMeasurement);
+    NSArray<id<SentrySpan>> *appStartSpans = [self isStandaloneAppStartTransaction]
+        ? sentryBuildStandaloneAppStartSpans(self, appStartMeasurement)
+        : sentryBuildAppStartSpans(self, appStartMeasurement);
     capacity = _children.count + appStartSpans.count;
 #else
     capacity = _children.count;
@@ -758,6 +773,13 @@ - (SentryTransaction *)toTransaction
 
 #if SENTRY_HAS_UIKIT
 
+- (BOOL)isStandaloneAppStartTransaction
+{
+    return [StandaloneAppStartTransactionHelper
+        isStandaloneAppStartTransactionWithOperation:self.operation
+                                              origin:self.origin];
+}
+
 - (void)addAppStartMeasurements:(SentryTransaction *)transaction
 {
     if (appStartMeasurement != nil && appStartMeasurement.type != SentryAppStartTypeUnknown) {

Sources/Sentry/include/SentryAppStartMeasurementProvider.h

@@ -21,6 +21,13 @@ NS_ASSUME_NONNULL_BEGIN
                                                          startTimestamp:
                                                              (nullable NSDate *)startTimestamp;
 
+/**
+ * Marks the app start measurement as read so subsequent calls to
+ * @c appStartMeasurementForOperation:startTimestamp: return @c nil.
+ * Used by standalone app start transactions that carry their own measurement.
+ */
++ (void)markAsRead;
+
 /**
  * Internal. Only needed for testing.
  */

Sources/Sentry/include/SentryBuildAppStartSpans.h

@@ -8,9 +8,39 @@ NS_ASSUME_NONNULL_BEGIN
 
 #if SENTRY_HAS_UIKIT
 
+/**
+ * Builds app start spans for a UIViewController transaction. An intermediate grouping span
+ * ("Cold Start" / "Warm Start") is inserted as parent for the phase spans:
+ *
+ * @code
+ *   UIViewController (op: ui.load)            ← tracer
+ *     └─ Cold Start (op: app.start.cold)      ← grouping span
+ *          ├─ Pre Runtime Init
+ *          ├─ Runtime Init to Pre Main Initializers
+ *          ├─ UIKit Init
+ *          ├─ Application Init
+ *          └─ Initial Frame Render
+ * @endcode
+ */
 NSArray<id<SentrySpan>> *sentryBuildAppStartSpans(
     SentryTracer *tracer, SentryAppStartMeasurement *_Nullable appStartMeasurement);
 
+/**
+ * Builds app start spans for a standalone app start transaction. Phase spans are parented
+ * directly to the tracer (no intermediate grouping span):
+ *
+ * @code
+ *   App Start Cold (op: app.start.cold)       ← tracer
+ *     ├─ Pre Runtime Init
+ *     ├─ Runtime Init to Pre Main Initializers
+ *     ├─ UIKit Init
+ *     ├─ Application Init
+ *     └─ Initial Frame Render
+ * @endcode
+ */
+NSArray<id<SentrySpan>> *sentryBuildStandaloneAppStartSpans(
+    SentryTracer *tracer, SentryAppStartMeasurement *_Nullable appStartMeasurement);
+
 #endif // SENTRY_HAS_UIKIT
 
 NS_ASSUME_NONNULL_END

Sources/Sentry/include/SentryPrivate.h

@@ -89,6 +89,7 @@
 #import "SentryTraceHeader.h"
 #import "SentryTraceOrigin.h"
 #import "SentryTraceProfiler.h"
+#import "SentryTracerConfiguration.h"
 #import "SentryUIViewControllerSwizzlingHelper.h"
 #import "SentryUncaughtNSExceptions.h"
 #import "SentryWatchdogTerminationBreadcrumbProcessor.h"

Sources/Sentry/include/SentrySpanOperation.h

@@ -36,6 +36,9 @@ SENTRY_EXTERN NSString *const SentrySpanOperationNetworkRequestOperation;
 SENTRY_EXTERN NSString *const SentrySpanOperationUiAction;
 SENTRY_EXTERN NSString *const SentrySpanOperationUiActionClick;
 
+SENTRY_EXTERN NSString *const SentrySpanOperationAppStartCold;
+SENTRY_EXTERN NSString *const SentrySpanOperationAppStartWarm;
+
 SENTRY_EXTERN NSString *const SentrySpanOperationUiLoad;
 
 SENTRY_EXTERN NSString *const SentrySpanOperationUiLoadInitialDisplay;

Sources/Sentry/include/SentryTracerConfiguration.h

@@ -8,6 +8,7 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+@class SentryAppStartMeasurement;
 @class SentryDispatchQueueWrapper;
 @class SentryProfileOptions;
 @class SentrySamplerDecision;
@@ -52,6 +53,17 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (nonatomic) NSTimeInterval idleTimeout;
 
+#if SENTRY_HAS_UIKIT
+/**
+ * The app start measurement to attach to this tracer.
+ * When set, the tracer uses this instead of reading from the global static in
+ * @c SentryAppStartMeasurementProvider.
+ *
+ * Default is nil.
+ */
+@property (nonatomic, strong, nullable) SentryAppStartMeasurement *appStartMeasurement;
+#endif // SENTRY_HAS_UIKIT
+
 + (SentryTracerConfiguration *)configurationWithBlock:
     (void (^)(SentryTracerConfiguration *configuration))block;
 

Sources/Swift/Helper/SentryEnabledFeaturesBuilder.swift

@@ -49,6 +49,9 @@ import Foundation
         if options.experimental.enableMetrics {
             features.append("metrics")
         }
+        if options.experimental.enableStandaloneAppStartTracing {
+            features.append("standaloneAppStartTracing")
+        }
 
         return features
     }