fix: TTID/TTFD transaction for the root page

CHANGELOG.md

@@ -5,6 +5,9 @@
 ### Fixes
 
 - Debug meta not loaded for split debug info only builds ([#3104](https://github.com/getsentry/sentry-dart/pull/3104))
+- TTID/TTFD root transactions ([#3099](https://github.com/getsentry/sentry-dart/pull/3099))
+  - Web, Linux and Windows now create a UI transaction for the root page
+  - iOS, Android now correctly create idle transactions
 
 ### Dependencies
 

dart/test/sentry_client_sdk_lifecycle_test.dart

@@ -0,0 +1,195 @@
+import 'package:sentry/sentry.dart';
+import 'package:sentry/src/platform/mock_platform.dart';
+import 'package:sentry/src/sentry_tracer.dart';
+import 'package:test/test.dart';
+
+import 'mocks/mock_client_report_recorder.dart';
+import 'mocks/mock_log_batcher.dart';
+import 'mocks/mock_transport.dart';
+import 'sentry_client_test.dart';
+import 'test_utils.dart';
+import 'utils/url_details_test.dart';
+
+void main() {
+  group('SDK lifecycle callbacks', () {
+    late Fixture fixture;
+
+    setUp(() => fixture = Fixture());
+
+    group('Logs', () {
+      SentryLog givenLog() {
+        return SentryLog(
+          timestamp: DateTime.now(),
+          traceId: SentryId.newId(),
+          level: SentryLogLevel.info,
+          body: 'test',
+          attributes: {
+            'attribute': SentryLogAttribute.string('value'),
+          },
+        );
+      }
+
+      test('captureLog triggers OnBeforeCaptureLog', () async {
+        fixture.options.enableLogs = true;
+        fixture.options.environment = 'test-environment';
+        fixture.options.release = 'test-release';
+
+        final log = givenLog();
+
+        final scope = Scope(fixture.options);
+        final span = MockSpan();
+        scope.span = span;
+
+        final client = fixture.getSut();
+        fixture.options.logBatcher = MockLogBatcher();
+
+        client.lifeCycleRegistry.registerCallback<OnBeforeCaptureLog>((event) {
+          event.log.attributes['test'] =
+              SentryLogAttribute.string('test-value');
+        });
+
+        await client.captureLog(log, scope: scope);
+
+        final mockLogBatcher = fixture.options.logBatcher as MockLogBatcher;
+        expect(mockLogBatcher.addLogCalls.length, 1);
+        final capturedLog = mockLogBatcher.addLogCalls.first;
+
+        expect(capturedLog.attributes['test']?.value, "test-value");
+        expect(capturedLog.attributes['test']?.type, 'string');
+      });
+    });
+
+    group('SentryEvent', () {
+      test('captureEvent triggers OnBeforeSendEvent', () async {
+        fixture.options.enableLogs = true;
+        fixture.options.environment = 'test-environment';
+        fixture.options.release = 'test-release';
+
+        final event = SentryEvent();
+
+        final scope = Scope(fixture.options);
+        final span = MockSpan();
+        scope.span = span;
+
+        final client = fixture.getSut();
+        fixture.options.logBatcher = MockLogBatcher();
+
+        client.lifeCycleRegistry.registerCallback<OnBeforeSendEvent>((event) {
+          event.event.release = '999';
+        });
+
+        await client.captureEvent(event, scope: scope);
+
+        final capturedEnvelope = (fixture.transport).envelopes.first;
+        final capturedEvent = await eventFromEnvelope(capturedEnvelope);
+
+        expect(capturedEvent.release, '999');
+      });
+    });
+  });
+}
+
+class Fixture {
+  final recorder = MockClientReportRecorder();
+  final transport = MockTransport();
+
+  final options = defaultTestOptions()
+    ..platform = MockPlatform.iOS()
+    ..groupExceptions = true;
+
+  late SentryTransactionContext _context;
+  late SentryTracer tracer;
+
+  SentryLevel? loggedLevel;
+  Object? loggedException;
+
+  SentryClient getSut({
+    bool sendDefaultPii = false,
+    bool attachStacktrace = true,
+    bool attachThreads = false,
+    double? sampleRate,
+    BeforeSendCallback? beforeSend,
+    BeforeSendTransactionCallback? beforeSendTransaction,
+    BeforeSendCallback? beforeSendFeedback,
+    EventProcessor? eventProcessor,
+    bool provideMockRecorder = true,
+    bool debug = false,
+    Transport? transport,
+  }) {
+    options.tracesSampleRate = 1.0;
+    options.sendDefaultPii = sendDefaultPii;
+    options.attachStacktrace = attachStacktrace;
+    options.attachThreads = attachThreads;
+    options.sampleRate = sampleRate;
+    options.beforeSend = beforeSend;
+    options.beforeSendTransaction = beforeSendTransaction;
+    options.beforeSendFeedback = beforeSendFeedback;
+    options.debug = debug;
+    options.log = mockLogger;
+
+    if (eventProcessor != null) {
+      options.addEventProcessor(eventProcessor);
+    }
+
+    // Internally also creates a SentryClient instance
+    final hub = Hub(options);
+    _context = SentryTransactionContext(
+      'name',
+      'op',
+    );
+    tracer = SentryTracer(_context, hub);
+
+    // Reset transport
+    options.transport = transport ?? this.transport;
+
+    // Again create SentryClient instance
+    final client = SentryClient(options);
+
+    if (provideMockRecorder) {
+      options.recorder = recorder;
+    }
+    return client;
+  }
+
+  Future<SentryEvent?> droppingBeforeSend(SentryEvent event, Hint hint) async {
+    return null;
+  }
+
+  SentryTransaction fakeTransaction() {
+    return SentryTransaction(
+      tracer,
+      sdk: SdkVersion(name: 'sdk1', version: '1.0.0'),
+      breadcrumbs: [],
+    );
+  }
+
+  SentryEvent fakeFeedbackEvent() {
+    return SentryEvent(
+      type: 'feedback',
+      contexts: Contexts(feedback: fakeFeedback()),
+      level: SentryLevel.info,
+    );
+  }
+
+  SentryFeedback fakeFeedback() {
+    return SentryFeedback(
+      message: 'fixture-message',
+      contactEmail: 'fixture-contactEmail',
+      name: 'fixture-name',
+      replayId: 'fixture-replayId',
+      url: "https://fixture-url.com",
+      associatedEventId: SentryId.fromId('1d49af08b6e2c437f9052b1ecfd83dca'),
+    );
+  }
+
+  void mockLogger(
+    SentryLevel level,
+    String message, {
+    String? logger,
+    Object? exception,
+    StackTrace? stackTrace,
+  }) {
+    loggedLevel = level;
+    loggedException = exception;
+  }
+}

flutter/lib/src/integrations/generic_app_start_integration.dart

@@ -0,0 +1,74 @@
+// ignore_for_file: invalid_use_of_internal_member
+
+import 'package:meta/meta.dart';
+
+import '../../sentry_flutter.dart';
+import '../frame_callback_handler.dart';
+
+// TODO(buenaflor): marking this internal until we can find a robust way to unify the TTID/TTFD implementation as currently it is very fragmented.
+
+/// A fallback app–start integration for platforms without built-in app-start timing.
+///
+/// The Sentry Cocoa and Android SDKs include calls to capture the
+/// exact application start timestamp. Other platforms—such as web, desktop,
+/// or any SDK that doesn’t (yet) expose app-start instrumentation can use this
+/// integration as a reasonable alternative. It measures the duration from
+/// integration call to the first completed frame.
+@internal
+class GenericAppStartIntegration extends Integration<SentryFlutterOptions> {
+  GenericAppStartIntegration([FrameCallbackHandler? frameHandler])
+      : _framesHandler = frameHandler ?? DefaultFrameCallbackHandler();
+
+  final FrameCallbackHandler _framesHandler;
+
+  static const String integrationName = 'GenericAppStart';
+
+  @override
+  void call(Hub hub, SentryFlutterOptions options) {
+    if (!options.isTracingEnabled()) return;
+
+    final transactionContext = SentryTransactionContext(
+      'root /',
+      SentrySpanOperations.uiLoad,
+      origin: SentryTraceOrigins.autoUiTimeToDisplay,
+    );
+
+    final startTimeStamp = options.clock();
+    final transaction = hub.startTransactionWithContext(
+      transactionContext,
+      startTimestamp: startTimeStamp,
+      waitForChildren: true,
+      autoFinishAfter: Duration(seconds: 3),
+      bindToScope: true,
+      trimEnd: true,
+    );
+
+    options.timeToDisplayTracker.transactionId = transactionContext.spanId;
+
+    _framesHandler.addPostFrameCallback((_) async {
+      try {
+        final endTimestamp = options.clock();
+        await options.timeToDisplayTracker.track(
+          transaction,
+          ttidEndTimestamp: endTimestamp,
+        );
+
+        // Note: we do not set app start transaction measurements (yet) on purpose
+        // This integration is used for TTID/TTFD mainly
+        // However this may change in the future.
+      } catch (exception, stackTrace) {
+        options.log(
+          SentryLevel.error,
+          'An exception occurred while executing the $GenericAppStartIntegration',
+          exception: exception,
+          stackTrace: stackTrace,
+        );
+        if (options.automatedTestMode) {
+          rethrow;
+        }
+      }
+    });
+
+    options.sdk.addIntegration(integrationName);
+  }
+}

flutter/lib/src/integrations/native_app_start_handler.dart

@@ -44,16 +44,10 @@ class NativeAppStartHandler {
     final rootScreenTransaction = _hub.startTransactionWithContext(
       context,
       startTimestamp: appStartInfo.start,
-    );
-
-    // Bind to scope if null
-    await _hub.configureScope((scope) {
-      scope.span ??= rootScreenTransaction;
-    });
-
-    await options.timeToDisplayTracker.track(
-      rootScreenTransaction,
-      ttidEndTimestamp: appStartInfo.end,
+      waitForChildren: true,
+      autoFinishAfter: Duration(seconds: 3),
+      bindToScope: true,
+      trimEnd: true,
     );
 
     SentryTracer sentryTracer;
@@ -63,20 +57,17 @@ class NativeAppStartHandler {
       return;
     }
 
-    // Enrich Transaction
+    // We need to add the measurements before we add the child spans
+    // If the child span finish the transaction will finish and then we cannot add measurements
+    // TODO(buenaflor): eventually we can move this to the onFinish callback
     SentryMeasurement? measurement = appStartInfo.toMeasurement();
     sentryTracer.measurements[measurement.name] = appStartInfo.toMeasurement();
-    await _attachAppStartSpans(appStartInfo, sentryTracer);
 
-    // Remove from scope
-    await _hub.configureScope((scope) {
-      if (scope.span == rootScreenTransaction) {
-        scope.span = null;
-      }
-    });
-
-    // Finish Transaction
-    await rootScreenTransaction.finish(endTimestamp: appStartInfo.end);
+    await options.timeToDisplayTracker.track(
+      rootScreenTransaction,
+      ttidEndTimestamp: appStartInfo.end,
+    );
+    await _attachAppStartSpans(appStartInfo, sentryTracer);
   }
 
   _AppStartInfo? _infoNativeAppStart(

flutter/lib/src/integrations/native_app_start_integration.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: invalid_use_of_internal_member
+
 import 'dart:ui';
 
 import 'package:meta/meta.dart';
@@ -31,8 +33,8 @@ class NativeAppStartIntegration extends Integration<SentryFlutterOptions> {
     // Create context early so we have an id to refernce for reporting full display
     final context = SentryTransactionContext(
       'root /',
-      // ignore: invalid_use_of_internal_member
       SentrySpanOperations.uiLoad,
+      origin: SentryTraceOrigins.autoUiTimeToDisplay,
     );
     options.timeToDisplayTracker.transactionId = context.spanId;
 
@@ -45,7 +47,6 @@ class NativeAppStartIntegration extends Integration<SentryFlutterOptions> {
       _allowProcessing = false;
 
       try {
-        // ignore: invalid_use_of_internal_member
         final appStartEnd = DateTime.fromMicrosecondsSinceEpoch(timings.first
             .timestampInMicroseconds(FramePhase.rasterFinishWallTime));
         await _nativeAppStartHandler.call(

flutter/lib/src/navigation/sentry_navigator_observer.dart

@@ -287,8 +287,8 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
     final routeName = _getRouteName(route) ?? _currentRouteName;
     final arguments = route?.settings.arguments;
 
-    final isRoot = routeName ==
-        '/'; // Root transaction is already created by the app start integration.
+    // Skip root - app start integrations create TTID/TTFD for root
+    final isRoot = routeName == '/';
     if (!_enableAutoTransactions || routeName == null || isRoot) {
       return;
     }