feat: ttid

CHANGELOG.md

@@ -9,6 +9,16 @@
 
 ### Features
 
+- Add TTID (time to initial display), which allows you to measure the time it takes to render the first frame of your screen ([#1910](https://github.com/getsentry/sentry-dart/pull/1910))
+  - Requires using the [routing instrumentation](https://docs.sentry.io/platforms/flutter/integrations/routing-instrumentation/).
+  - Introduces two modes: 
+    - `automatic` mode is enabled by default for all screens and will yield only an approximation result.
+    - `manual` mode requires manual instrumentation and will yield a more accurate result.
+      - To use `manual` mode, you need to wrap your desired widget: `SentryDisplayWidget(child: MyScreen())`.
+    - You can mix and match both modes in your app.
+  - Other significant fixes
+    - `didPop` doesn't trigger a new transaction
+    - Change transaction operation name to `ui.load` instead of `navigation`
 - Use `recordHttpBreadcrumbs` to set iOS `enableNetworkBreadcrumbs` ([#1884](https://github.com/getsentry/sentry-dart/pull/1884))
 
 ### Improvements

dart/lib/sentry.dart

@@ -49,6 +49,8 @@ export 'src/utils/http_header_utils.dart';
 // ignore: invalid_export_of_internal_element
 export 'src/sentry_trace_origins.dart';
 // ignore: invalid_export_of_internal_element
+export 'src/sentry_span_operations.dart';
+// ignore: invalid_export_of_internal_element
 export 'src/utils.dart';
 // spotlight debugging
 export 'src/spotlight.dart';

dart/lib/src/sentry_measurement.dart

@@ -39,6 +39,13 @@ class SentryMeasurement {
         value = duration.inMilliseconds,
         unit = DurationSentryMeasurementUnit.milliSecond;
 
+  /// Duration of the time to initial display in milliseconds
+  SentryMeasurement.timeToInitialDisplay(Duration duration)
+      : assert(!duration.isNegative),
+        name = 'time_to_initial_display',
+        value = duration.inMilliseconds,
+        unit = DurationSentryMeasurementUnit.milliSecond;
+
   final String name;
   final num value;
   final SentryMeasurementUnit? unit;

dart/lib/src/sentry_span_operations.dart

@@ -0,0 +1,7 @@
+import 'package:meta/meta.dart';
+
+@internal
+class SentrySpanOperations {
+  static const String uiLoad = 'ui.load';
+  static const String uiTimeToInitialDisplay = 'ui.load.initial_display';
+}

dart/lib/src/sentry_trace_origins.dart

@@ -27,4 +27,6 @@ class SentryTraceOrigins {
   static const autoDbDriftQueryExecutor = 'auto.db.drift.query.executor';
   static const autoDbDriftTransactionExecutor =
       'auto.db.drift.transaction.executor';
+  static const autoUiTimeToDisplay = 'auto.ui.time_to_display';
+  static const manualUiTimeToDisplay = 'manual.ui.time_to_display';
 }

flutter/example/android/app/build.gradle

@@ -48,7 +48,7 @@ android {
 
     defaultConfig {
         applicationId "io.sentry.samples.flutter"
-        minSdkVersion 19
+        minSdkVersion flutter.minSdkVersion
         targetSdkVersion 33
         versionCode flutterVersionCode.toInteger()
         versionName flutterVersionName

flutter/example/lib/main.dart

@@ -80,6 +80,7 @@ Future<void> setupSentry(
       // going to log too much for your app, but can be useful when figuring out
       // configuration issues, e.g. finding out why your events are not uploaded.
       options.debug = true;
+      options.spotlight = Spotlight(enabled: true);
 
       options.maxRequestBodySize = MaxRequestBodySize.always;
       options.maxResponseBodySize = MaxResponseBodySize.always;

flutter/lib/src/integrations/native_app_start_integration.dart

@@ -114,9 +114,9 @@ class AppStartInfo {
   final AppStartType type;
   final DateTime start;
   final DateTime end;
+  Duration get duration => end.difference(start);
 
   SentryMeasurement toMeasurement() {
-    final duration = end.difference(start);
     return type == AppStartType.cold
         ? SentryMeasurement.coldAppStart(duration)
         : SentryMeasurement.warmAppStart(duration);

flutter/lib/src/navigation/sentry_display_widget.dart

@@ -0,0 +1,60 @@
+import 'package:flutter/cupertino.dart';
+import 'time_to_initial_display_tracker.dart';
+
+import '../frame_callback_handler.dart';
+
+/// A widget that reports the Time To Initially Displayed (TTID) of its child widget.
+///
+/// This widget wraps around another widget to measure and report the time it takes
+/// for the child widget to be initially displayed on the screen. This method
+/// allows a more accurate measurement than what the default TTID implementation
+/// provides. The TTID measurement begins when the route to the widget is pushed and ends
+/// when [WidgetsBinding.instance.addPostFrameCallback] is triggered.
+///
+/// Wrap the widget you want to measure with [SentryDisplayWidget], and ensure that you
+/// have set up Sentry's routing instrumentation according to the Sentry documentation.
+///
+/// ```dart
+/// SentryDisplayWidget(
+///   child: MyWidget(),
+/// )
+/// ```
+///
+/// Make sure to configure Sentry's routing instrumentation in your app by following
+/// the guidelines provided in Sentry's documentation for Flutter integrations:
+/// https://docs.sentry.io/platforms/flutter/integrations/routing-instrumentation/
+///
+/// See also:
+/// - [Sentry's documentation on Flutter integrations](https://docs.sentry.io/platforms/flutter/)
+///   for more information on how to integrate Sentry into your Flutter application.
+class SentryDisplayWidget extends StatefulWidget {
+  final Widget child;
+  final FrameCallbackHandler _frameCallbackHandler;
+
+  SentryDisplayWidget({
+    super.key,
+    required this.child,
+    @visibleForTesting FrameCallbackHandler? frameCallbackHandler,
+  }) : _frameCallbackHandler =
+            frameCallbackHandler ?? DefaultFrameCallbackHandler();
+
+  @override
+  _SentryDisplayWidgetState createState() => _SentryDisplayWidgetState();
+}
+
+class _SentryDisplayWidgetState extends State<SentryDisplayWidget> {
+  @override
+  void initState() {
+    super.initState();
+    TimeToInitialDisplayTracker().markAsManual();
+
+    widget._frameCallbackHandler.addPostFrameCallback((_) {
+      TimeToInitialDisplayTracker().completeTracking();
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return widget.child;
+  }
+}

flutter/lib/src/navigation/sentry_navigator_observer.dart

@@ -1,5 +1,12 @@
+// ignore_for_file: invalid_use_of_internal_member
+
+import 'dart:async';
+
+import 'package:flutter/material.dart';
 import 'package:flutter/widgets.dart';
 import 'package:meta/meta.dart';
+import '../integrations/integrations.dart';
+import 'time_to_display_tracker.dart';
 
 import '../../sentry_flutter.dart';
 import '../event_processor/flutter_enricher_event_processor.dart';
@@ -19,6 +26,8 @@ typedef AdditionalInfoExtractor = Map<String, dynamic>? Function(
 /// This is a navigation observer to record navigational breadcrumbs.
 /// For now it only records navigation events and no gestures.
 ///
+/// It also records Time to Initial Display (TTID).
+///
 /// [Route]s can always be null and their [Route.settings] can also always be null.
 /// For example, if the application starts, there is no previous route.
 /// The [RouteSettings] is null if a developer has not specified any
@@ -44,29 +53,29 @@ typedef AdditionalInfoExtractor = Map<String, dynamic>? Function(
 /// )
 /// ```
 ///
-/// See the constructor docs for the argument documentation.
+/// The option [enableAutoTransactions] is enabled by default. For every new
+/// route a transaction is started. It's automatically finished after
+/// [autoFinishAfter] duration or when all child spans are finished,
+/// if those happen to take longer. The transaction will be set to [Scope.span]
+/// if the latter is empty.
+///
+/// Enabling the [setRouteNameAsTransaction] option overrides the current
+/// [Scope.transaction] which will also override the name of the current
+/// [Scope.span]. So be careful when this is used together with performance
+/// monitoring.
 ///
 /// See also:
 ///   - [RouteObserver](https://api.flutter.dev/flutter/widgets/RouteObserver-class.html)
 ///   - [Navigating with arguments](https://flutter.dev/docs/cookbook/navigation/navigate-with-arguments)
 class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
-  /// The option [enableAutoTransactions] is enabled by default.
-  /// For every new route a transaction is started. It's automatically finished
-  /// after [autoFinishAfter] duration or when all child spans are
-  /// finished, if those happen to take longer.
-  /// The transaction will be set to [Scope.span] if the latter is empty.
-  ///
-  /// Enabling the [setRouteNameAsTransaction] option overrides the
-  /// current [Scope.transaction] which will also override the name of the current
-  /// [Scope.span]. So be careful when this is used together with performance
-  /// monitoring.
   SentryNavigatorObserver({
     Hub? hub,
     bool enableAutoTransactions = true,
     Duration autoFinishAfter = const Duration(seconds: 3),
     bool setRouteNameAsTransaction = false,
     RouteNameExtractor? routeNameExtractor,
     AdditionalInfoExtractor? additionalInfoProvider,
+    @visibleForTesting TimeToDisplayTracker? timeToDisplayTracker,
   })  : _hub = hub ?? HubAdapter(),
         _enableAutoTransactions = enableAutoTransactions,
         _autoFinishAfter = autoFinishAfter,
@@ -75,9 +84,9 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
         _additionalInfoProvider = additionalInfoProvider,
         _native = SentryFlutter.native {
     if (enableAutoTransactions) {
-      // ignore: invalid_use_of_internal_member
       _hub.options.sdk.addIntegration('UINavigationTracing');
     }
+    _timeToDisplayTracker = timeToDisplayTracker ?? TimeToDisplayTracker();
   }
 
   final Hub _hub;
@@ -88,13 +97,25 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
   final AdditionalInfoExtractor? _additionalInfoProvider;
   final SentryNative? _native;
 
+  static TimeToDisplayTracker? _timeToDisplayTracker;
+
+  @internal
+  static TimeToDisplayTracker? get timeToDisplayTracker =>
+      _timeToDisplayTracker;
+
   ISentrySpan? _transaction;
 
   static String? _currentRouteName;
 
   @internal
   static String? get currentRouteName => _currentRouteName;
 
+  Completer<void>? _completedDisplayTracking;
+
+  // Since didPush does not have a future, we can keep track of when the display tracking has finished
+  @visibleForTesting
+  Completer<void>? get completedDisplayTracking => _completedDisplayTracking;
+
   @override
   void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
     super.didPush(route, previousRoute);
@@ -109,7 +130,7 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
     );
 
     _finishTransaction();
-    _startTransaction(route);
+    _startTimeToDisplayTracking(route);
   }
 
   @override
@@ -140,7 +161,6 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
     );
 
     _finishTransaction();
-    _startTransaction(previousRoute);
   }
 
   void _addBreadcrumb({
@@ -152,7 +172,6 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
       navigationType: type,
       from: _routeNameExtractor?.call(from) ?? from,
       to: _routeNameExtractor?.call(to) ?? to,
-      // ignore: invalid_use_of_internal_member
       timestamp: _hub.options.clock(),
       data: _additionalInfoProvider?.call(from, to),
     ));
@@ -179,7 +198,20 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
     }
   }
 
-  Future<void> _startTransaction(Route<dynamic>? route) async {
+  Future<void> _finishTransaction() async {
+    _timeToDisplayTracker?.clear();
+
+    final transaction = _transaction;
+    _transaction = null;
+    if (transaction == null || transaction.finished) {
+      return;
+    }
+    transaction.status ??= SpanStatus.ok();
+    await transaction.finish();
+  }
+
+  Future<void> _startTransaction(
+      Route<dynamic>? route, DateTime startTimestamp) async {
     if (!_enableAutoTransactions) {
       return;
     }
@@ -196,14 +228,14 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
     }
     final transactionContext = SentryTransactionContext(
       name,
-      'navigation',
+      SentrySpanOperations.uiLoad,
       transactionNameSource: SentryTransactionNameSource.component,
-      // ignore: invalid_use_of_internal_member
       origin: SentryTraceOrigins.autoNavigationRouteObserver,
     );
 
     _transaction = _hub.startTransactionWithContext(
       transactionContext,
+      startTimestamp: startTimestamp,
       waitForChildren: true,
       autoFinishAfter: _autoFinishAfter,
       trimEnd: true,
@@ -242,14 +274,41 @@ class SentryNavigatorObserver extends RouteObserver<PageRoute<dynamic>> {
     await _native?.beginNativeFramesCollection();
   }
 
-  Future<void> _finishTransaction() async {
+  Future<void> _startTimeToDisplayTracking(Route<dynamic>? route) async {
+    _completedDisplayTracking = Completer<void>();
+    String? routeName = _currentRouteName;
+    if (routeName == null) return;
+
+    DateTime startTimestamp = _hub.options.clock();
+    DateTime? endTimestamp;
+
+    if (routeName == '/') {
+      final appStartInfo = await NativeAppStartIntegration.getAppStartInfo();
+      if (appStartInfo == null) {
+        return;
+      }
+
+      startTimestamp = appStartInfo.start;
+      endTimestamp = appStartInfo.end;
+    }
+
+    await _startTransaction(route, startTimestamp);
     final transaction = _transaction;
-    _transaction = null;
-    if (transaction == null || transaction.finished) {
+    if (transaction == null) {
       return;
     }
-    transaction.status ??= SpanStatus.ok();
-    await transaction.finish();
+
+    if (routeName == '/' && endTimestamp != null) {
+      await _timeToDisplayTracker?.trackAppStartTTD(transaction,
+          startTimestamp: startTimestamp, endTimestamp: endTimestamp);
+    } else {
+      await _timeToDisplayTracker?.trackRegularRouteTTD(transaction,
+          startTimestamp: startTimestamp);
+    }
+
+    // Mark the tracking as completed and clear any temporary state.
+    _completedDisplayTracking?.complete();
+    _timeToDisplayTracker?.clear();
   }
 }
 

flutter/lib/src/navigation/time_to_display_tracker.dart

@@ -0,0 +1,34 @@
+// ignore_for_file: invalid_use_of_internal_member
+
+import 'dart:async';
+
+import 'package:meta/meta.dart';
+
+import '../../sentry_flutter.dart';
+import 'time_to_initial_display_tracker.dart';
+
+@internal
+class TimeToDisplayTracker {
+  final TimeToInitialDisplayTracker _ttidTracker;
+
+  TimeToDisplayTracker({
+    TimeToInitialDisplayTracker? ttidTracker,
+  }) : _ttidTracker = ttidTracker ?? TimeToInitialDisplayTracker();
+
+  Future<void> trackAppStartTTD(ISentrySpan transaction,
+      {required DateTime startTimestamp,
+      required DateTime endTimestamp}) async {
+    // We start and immediately finish the spans since we cannot mutate the history of spans.
+    await _ttidTracker.trackAppStart(transaction,
+        startTimestamp: startTimestamp, endTimestamp: endTimestamp);
+  }
+
+  Future<void> trackRegularRouteTTD(ISentrySpan transaction,
+      {required DateTime startTimestamp}) async {
+    await _ttidTracker.trackRegularRoute(transaction, startTimestamp);
+  }
+
+  void clear() {
+    _ttidTracker.clear();
+  }
+}