feat(span-first): Port native app start integration to V2 span API

packages/dart/lib/src/hub.dart

@@ -715,8 +715,12 @@ class Hub {
     String name, {
     SentrySpanV2? parentSpan = const UnsetSentrySpanV2(),
     Map<String, SentryAttribute>? attributes,
+    DateTime? startTimestamp,
   }) =>
-      _createSpan(name, parentSpan: parentSpan, attributes: attributes);
+      _createSpan(name,
+          parentSpan: parentSpan,
+          attributes: attributes,
+          startTimestamp: startTimestamp);
 
   /// Returns `true` if the hub is able to create spans.
   bool get _canCreateSpansV2 {
@@ -790,6 +794,7 @@ class Hub {
     String name, {
     SentrySpanV2? parentSpan = const UnsetSentrySpanV2(),
     Map<String, SentryAttribute>? attributes,
+    DateTime? startTimestamp,
   }) {
     if (!_canCreateSpansV2) return NoOpSentrySpanV2.instance;
 
@@ -833,6 +838,7 @@ class Hub {
         clock: options.clock,
         dscCreator: _dscCreator,
         samplingDecision: samplingDecision,
+        startTimestamp: startTimestamp,
       );
     } else {
       span = RecordingSentrySpanV2.child(
@@ -841,6 +847,7 @@ class Hub {
         onSpanEnd: captureSpan,
         clock: options.clock,
         dscCreator: _dscCreator,
+        startTimestamp: startTimestamp,
       );
     }
 
@@ -862,6 +869,7 @@ class Hub {
     Duration finalTimeout = const Duration(seconds: 30),
     bool trimIdleSpanEndTimestamp = true,
     Map<String, SentryAttribute>? attributes,
+    DateTime? startTimestamp,
   }) {
     if (_currentIdleSpan != null) {
       internalLogger.warning(
@@ -887,6 +895,7 @@ class Hub {
       finalTimeout: finalTimeout,
       trimEndTimestamp: trimIdleSpanEndTimestamp,
       lifecycleRegistry: _options.lifecycleRegistry,
+      startTimestamp: startTimestamp,
     );
 
     if (attributes != null) {

packages/dart/lib/src/hub_adapter.dart

@@ -168,11 +168,13 @@ class HubAdapter implements Hub {
     String name, {
     SentrySpanV2? parentSpan = const UnsetSentrySpanV2(),
     Map<String, SentryAttribute>? attributes,
+    DateTime? startTimestamp,
   }) =>
       Sentry.currentHub.startInactiveSpan(
         name,
         parentSpan: parentSpan,
         attributes: attributes,
+        startTimestamp: startTimestamp,
       );
 
   @override
@@ -250,12 +252,14 @@ class HubAdapter implements Hub {
     Duration finalTimeout = const Duration(seconds: 30),
     bool trimIdleSpanEndTimestamp = true,
     Map<String, SentryAttribute>? attributes,
+    DateTime? startTimestamp,
   }) =>
       Sentry.currentHub.startIdleSpan(
         name,
         idleTimeout: idleTimeout,
         finalTimeout: finalTimeout,
         trimIdleSpanEndTimestamp: trimIdleSpanEndTimestamp,
         attributes: attributes,
+        startTimestamp: startTimestamp,
       );
 }

packages/dart/lib/src/noop_hub.dart

@@ -161,6 +161,7 @@ class NoOpHub implements Hub {
     String name, {
     SentrySpanV2? parentSpan = const UnsetSentrySpanV2(),
     Map<String, SentryAttribute>? attributes,
+    DateTime? startTimestamp,
   }) =>
       NoOpSentrySpanV2.instance;
 
@@ -187,6 +188,7 @@ class NoOpHub implements Hub {
     Duration finalTimeout = const Duration(seconds: 30),
     bool trimIdleSpanEndTimestamp = true,
     Map<String, SentryAttribute>? attributes,
+    DateTime? startTimestamp,
   }) =>
       NoOpSentrySpanV2.instance;
 }

packages/dart/lib/src/telemetry/span/idle_recording_sentry_span_v2.dart

@@ -42,6 +42,7 @@ final class IdleRecordingSentrySpanV2 extends RecordingSentrySpanV2 {
     required this.finalTimeout,
     required this.trimEndTimestamp,
     required SdkLifecycleRegistry lifecycleRegistry,
+    super.startTimestamp,
   })  : _lifecycleRegistry = lifecycleRegistry,
         super._(parentSpan: null) {
     _lifecycleRegistry.registerCallback<OnSpanStartV2>(_onSpanStartEvent);

packages/dart/lib/src/telemetry/span/recording_sentry_span_v2.dart

@@ -20,14 +20,14 @@ base class RecordingSentrySpanV2 implements SentrySpanV2 {
   final RecordingSentrySpanV2? _parentSpan;
   final ClockProvider _clock;
   final OnSpanEndCallback _onSpanEnd;
-  final DateTime _startTimestamp;
   final SentryId _traceId;
   final RecordingSentrySpanV2? _segmentSpan;
   final DscCreatorCallback _dscCreator;
   final Map<String, SentryAttribute> _attributes = {};
   final SentryTracesSamplingDecision _samplingDecision;
 
   // Mutable span state.
+  DateTime _startTimestamp;
   SentrySpanStatusV2 _status = SentrySpanStatusV2.ok;
   DateTime? _endTimestamp;
   String _name;
@@ -42,12 +42,13 @@ base class RecordingSentrySpanV2 implements SentrySpanV2 {
     required RecordingSentrySpanV2? parentSpan,
     required DscCreatorCallback dscCreator,
     required SentryTracesSamplingDecision samplingDecision,
+    DateTime? startTimestamp,
   })  : _traceId = parentSpan?.traceId ?? traceId,
         _name = name,
         _parentSpan = parentSpan,
         _clock = clock,
         _onSpanEnd = onSpanEnd,
-        _startTimestamp = clock(),
+        _startTimestamp = (startTimestamp ?? clock()).toUtc(),
         _segmentSpan = parentSpan?.segmentSpan,
         _dscCreator = dscCreator,
         _samplingDecision = samplingDecision;
@@ -62,6 +63,7 @@ base class RecordingSentrySpanV2 implements SentrySpanV2 {
     required ClockProvider clock,
     required DscCreatorCallback dscCreator,
     required SentryTracesSamplingDecision samplingDecision,
+    DateTime? startTimestamp,
   }) {
     return RecordingSentrySpanV2._(
       traceId: traceId,
@@ -71,6 +73,7 @@ base class RecordingSentrySpanV2 implements SentrySpanV2 {
       parentSpan: null,
       dscCreator: dscCreator,
       samplingDecision: samplingDecision,
+      startTimestamp: startTimestamp,
     );
   }
 
@@ -84,6 +87,7 @@ base class RecordingSentrySpanV2 implements SentrySpanV2 {
     required OnSpanEndCallback onSpanEnd,
     required ClockProvider clock,
     required DscCreatorCallback dscCreator,
+    DateTime? startTimestamp,
   }) {
     return RecordingSentrySpanV2._(
       traceId: parent.traceId,
@@ -93,6 +97,7 @@ base class RecordingSentrySpanV2 implements SentrySpanV2 {
       parentSpan: parent,
       dscCreator: dscCreator,
       samplingDecision: parent.samplingDecision,
+      startTimestamp: startTimestamp,
     );
   }
 
@@ -120,6 +125,9 @@ base class RecordingSentrySpanV2 implements SentrySpanV2 {
   @override
   DateTime get startTimestamp => _startTimestamp;
 
+  @internal
+  set startTimestamp(DateTime value) => _startTimestamp = value.toUtc();
+
   @override
   DateTime? get endTimestamp => _endTimestamp;
 

packages/dart/test/hub_span_test.dart

@@ -93,6 +93,39 @@ void main() {
 
           expect(hub.scope.getActiveSpan(), isNull);
         });
+
+        test('uses startTimestamp when provided', () {
+          final hub = fixture.getSut();
+          final past = DateTime(2024, 1, 1, 12, 0, 0);
+
+          final span = hub.startInactiveSpan('test-span', startTimestamp: past)
+              as RecordingSentrySpanV2;
+
+          expect(span.startTimestamp, equals(past.toUtc()));
+        });
+
+        test('uses clock when startTimestamp is not provided', () {
+          final hub = fixture.getSut();
+
+          final span =
+              hub.startInactiveSpan('test-span') as RecordingSentrySpanV2;
+
+          expect(span.startTimestamp, isNotNull);
+          expect(span.startTimestamp.difference(DateTime.now()).abs(),
+              lessThan(Duration(seconds: 1)));
+        });
+
+        test('child span uses startTimestamp when provided', () {
+          final hub = fixture.getSut();
+          final past = DateTime(2024, 1, 1, 12, 0, 0);
+
+          final root = hub.startInactiveSpan('root', parentSpan: null);
+          final child = hub.startInactiveSpan('child',
+              parentSpan: root, startTimestamp: past) as RecordingSentrySpanV2;
+
+          expect(child.startTimestamp, equals(past.toUtc()));
+          expect(child.startTimestamp.isUtc, isTrue);
+        });
       });
 
       group('when ignoreSpans rules are configured', () {
@@ -702,6 +735,21 @@ void main() {
     });
 
     group('when using idle spans', () {
+      test('uses startTimestamp when provided', () {
+        final hub = fixture.getSut();
+        final past = DateTime(2024, 1, 1, 12, 0, 0);
+
+        final idleSpan = hub.startIdleSpan(
+          'idle-root',
+          startTimestamp: past,
+          idleTimeout: Duration(seconds: 1),
+          finalTimeout: Duration(seconds: 2),
+        ) as RecordingSentrySpanV2;
+
+        expect(idleSpan.startTimestamp, equals(past.toUtc()));
+        expect(idleSpan.startTimestamp.isUtc, isTrue);
+      });
+
       test('clears active idle span when ended directly', () async {
         final hub = fixture.getSut();
         final idleSpan = hub.startIdleSpan(

packages/flutter/example/lib/main.dart

@@ -155,11 +155,18 @@ class _MyAppState extends State<MyApp> {
   @override
   void initState() {
     super.initState();
+
+    doWork();
+  }
+
+  void doWork() async {
     final rootDisplay = SentryFlutter.currentDisplay();
-    Future.delayed(const Duration(seconds: 3), () {
-      // Do some long running work...
-      rootDisplay?.reportFullyDisplayed();
+
+    await Sentry.startSpan('Custom span that runs during app start', (_) async {
+      await Future.delayed(const Duration(seconds: 1));
     });
+
+    rootDisplay?.reportFullyDisplayed();
   }
 
   @override

packages/flutter/lib/src/integrations/generic_app_start_integration.dart

@@ -27,6 +27,12 @@ class GenericAppStartIntegration extends Integration<SentryFlutterOptions> {
   void call(Hub hub, SentryFlutterOptions options) {
     if (!options.isTracingEnabled()) return;
 
+    if (options.traceLifecycle == SentryTraceLifecycle.streaming) {
+      options.timeToDisplayTrackerV2.trackRootNavigation();
+      options.sdk.addIntegration(integrationName);
+      return;
+    }
+
     final transactionContext = SentryTransactionContext(
       'root /',
       SentrySpanOperations.uiLoad,

packages/flutter/lib/src/integrations/native_app_start_data.dart

@@ -0,0 +1,122 @@
+// ignore_for_file: invalid_use_of_internal_member
+
+import 'package:meta/meta.dart';
+
+import '../../sentry_flutter.dart';
+import '../native/native_app_start.dart';
+import '../utils/internal_logger.dart';
+
+/// We filter out App starts more than 60s
+@internal
+const maxAppStartMillis = 60000;
+
+@internal
+enum AppStartType { cold, warm }
+
+@internal
+class AppStartInfo {
+  AppStartInfo(
+    this.type, {
+    required this.start,
+    required this.end,
+    required this.pluginRegistration,
+    required this.sentrySetupStart,
+    required this.nativeSpanTimes,
+  });
+
+  final AppStartType type;
+  final DateTime start;
+  final DateTime end;
+  final List<TimeSpan> nativeSpanTimes;
+
+  final DateTime pluginRegistration;
+  final DateTime sentrySetupStart;
+
+  Duration get duration => end.difference(start);
+
+  SentryMeasurement toMeasurement() {
+    final duration = this.duration;
+    return type == AppStartType.cold
+        ? SentryMeasurement.coldAppStart(duration)
+        : SentryMeasurement.warmAppStart(duration);
+  }
+
+  String get appStartTypeOperation => 'app.start.${type.name}';
+
+  String get appStartTypeDescription =>
+      type == AppStartType.cold ? 'Cold Start' : 'Warm Start';
+  final pluginRegistrationDescription = 'App start to plugin registration';
+  final sentrySetupDescription = 'Before Sentry Init Setup';
+  final firstFrameRenderDescription = 'First frame render';
+}
+
+@internal
+class TimeSpan {
+  TimeSpan({required this.start, required this.end, required this.description});
+
+  final DateTime start;
+  final DateTime end;
+  final String description;
+}
+
+/// Parses and validates native app start data.
+///
+/// Returns `null` if validation fails (e.g. >60s duration, missing setup time).
+@internal
+AppStartInfo? parseNativeAppStart(
+  NativeAppStart nativeAppStart,
+  DateTime appStartEnd,
+) {
+  final sentrySetupStartDateTime = SentryFlutter.sentrySetupStartTime;
+  if (sentrySetupStartDateTime == null) {
+    return null;
+  }
+
+  final appStartDateTime =
+      DateTime.fromMillisecondsSinceEpoch(nativeAppStart.appStartTime);
+  final pluginRegistrationDateTime = DateTime.fromMillisecondsSinceEpoch(
+      nativeAppStart.pluginRegistrationTime);
+
+  final duration = appStartEnd.difference(appStartDateTime);
+
+  // We filter out app start more than 60s.
+  // This could be due to many different reasons.
+  // If you do the manual init and init the SDK too late and it does not
+  // compute the app start end in the very first Screen.
+  // If the process starts but the App isn't in the foreground.
+  // If the system forked the process earlier to accelerate the app start.
+  // And some unknown reasons that could not be reproduced.
+  // We've seen app starts with hours, days and even months.
+  if (duration.inMilliseconds > maxAppStartMillis) {
+    return null;
+  }
+
+  List<TimeSpan> nativeSpanTimes = [];
+  for (final entry in nativeAppStart.nativeSpanTimes.entries) {
+    try {
+      final startTimestampMs = entry.value['startTimestampMsSinceEpoch'] as int;
+      final endTimestampMs = entry.value['stopTimestampMsSinceEpoch'] as int;
+      nativeSpanTimes.add(TimeSpan(
+        start: DateTime.fromMillisecondsSinceEpoch(startTimestampMs),
+        end: DateTime.fromMillisecondsSinceEpoch(endTimestampMs),
+        description: entry.key as String,
+      ));
+    } catch (e) {
+      internalLogger.warning('Failed to parse native span times: $e');
+      continue;
+    }
+  }
+
+  // We want to sort because the native spans are not guaranteed to be in order.
+  // Performance wise this won't affect us since the native span amount is very low.
+  nativeSpanTimes.sort((a, b) => a.start.compareTo(b.start));
+
+  return AppStartInfo(
+    nativeAppStart.isColdStart ? AppStartType.cold : AppStartType.warm,
+    start: appStartDateTime,
+    end: appStartEnd,
+    pluginRegistration: pluginRegistrationDateTime,
+    sentrySetupStart: sentrySetupStartDateTime,
+    nativeSpanTimes: nativeSpanTimes,
+  );
+}