feat(performance): report total frames, frame delay, slow & frozen frames

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Capture total frames, frame delay, slow & frozen frames and attach to spans ([#2106](https://github.com/getsentry/sentry-dart/pull/2106))
+
 ### Fixes
 
 - Load contexts integration not setting `SentryUser` ([#2089](https://github.com/getsentry/sentry-dart/pull/2089))

dart/lib/sentry.dart

@@ -30,6 +30,7 @@ export 'src/http_client/sentry_http_client_error.dart';
 export 'src/sentry_attachment/sentry_attachment.dart';
 export 'src/sentry_user_feedback.dart';
 export 'src/utils/tracing_utils.dart';
+export 'src/performance_collector.dart';
 // tracing
 export 'src/tracing.dart';
 export 'src/hint.dart';

dart/lib/src/hub.dart

@@ -409,22 +409,24 @@ class Hub {
     bool? trimEnd,
     OnTransactionFinish? onFinish,
     Map<String, dynamic>? customSamplingContext,
-  }) =>
-      startTransactionWithContext(
-        SentryTransactionContext(
-          name,
-          operation,
-          description: description,
-          origin: SentryTraceOrigins.manual,
-        ),
-        startTimestamp: startTimestamp,
-        bindToScope: bindToScope,
-        waitForChildren: waitForChildren,
-        autoFinishAfter: autoFinishAfter,
-        trimEnd: trimEnd,
-        onFinish: onFinish,
-        customSamplingContext: customSamplingContext,
-      );
+  }) {
+    final tx = startTransactionWithContext(
+      SentryTransactionContext(
+        name,
+        operation,
+        description: description,
+        origin: SentryTraceOrigins.manual,
+      ),
+      startTimestamp: startTimestamp,
+      bindToScope: bindToScope,
+      waitForChildren: waitForChildren,
+      autoFinishAfter: autoFinishAfter,
+      trimEnd: trimEnd,
+      onFinish: onFinish,
+      customSamplingContext: customSamplingContext,
+    );
+    return tx;
+  }
 
   /// Creates a Transaction and returns the instance.
   ISentrySpan startTransactionWithContext(

dart/lib/src/performance_collector.dart

@@ -0,0 +1,13 @@
+import '../sentry.dart';
+
+abstract class PerformanceCollector {}
+
+/// Used for collecting continuous data about vitals (slow, frozen frames, etc.)
+/// during a transaction/span.
+abstract class PerformanceContinuousCollector extends PerformanceCollector {
+  void onSpanStarted(ISentrySpan span);
+
+  void onSpanFinished(ISentrySpan span, DateTime endTimestamp);
+
+  void clear();
+}

dart/lib/src/protocol/sentry_span.dart

@@ -1,12 +1,9 @@
 import 'dart:async';
 
-import '../hub.dart';
+import '../../sentry.dart';
 import '../metrics/local_metrics_aggregator.dart';
-import '../protocol.dart';
 
 import '../sentry_tracer.dart';
-import '../tracing.dart';
-import '../utils.dart';
 
 typedef OnFinishedCallback = Future<void> Function({DateTime? endTimestamp});
 
@@ -16,6 +13,9 @@ class SentrySpan extends ISentrySpan {
   Map<String, List<MetricSummary>>? _metricSummaries;
   late final DateTime _startTimestamp;
   final Hub _hub;
+  bool _isRootSpan = false;
+
+  bool get isRootSpan => _isRootSpan;
 
   final SentryTracer _tracer;
   final Map<String, dynamic> _data = {};
@@ -36,13 +36,15 @@ class SentrySpan extends ISentrySpan {
     DateTime? startTimestamp,
     this.samplingDecision,
     OnFinishedCallback? finishedCallback,
+    isRootSpan = false,
   }) {
     _startTimestamp = startTimestamp?.toUtc() ?? _hub.options.clock();
     _finishedCallback = finishedCallback;
     _origin = _context.origin;
     _localMetricsAggregator = _hub.options.enableSpanLocalMetricAggregation
         ? LocalMetricsAggregator()
         : null;
+    _isRootSpan = isRootSpan;
   }
 
   @override
@@ -67,12 +69,24 @@ class SentrySpan extends ISentrySpan {
       _endTimestamp = endTimestamp.toUtc();
     }
 
+    print('finishing: ${_context.description}');
+    // We need the timestamp so we can finish here
+    for (final collector in _hub.options.performanceCollectors) {
+      if (collector is PerformanceContinuousCollector) {
+        final _timestamp = _endTimestamp;
+        if (_timestamp != null) {
+          collector.onSpanFinished(this, _timestamp);
+        }
+      }
+    }
+
     // associate error
     if (_throwable != null) {
       _hub.setSpanContext(_throwable, this, _tracer.name);
     }
     _metricSummaries = _localMetricsAggregator?.getSummaries();
     await _finishedCallback?.call(endTimestamp: _endTimestamp);
+    _finished = true;
     return super.finish(status: status, endTimestamp: _endTimestamp);
   }
 
@@ -197,8 +211,10 @@ class SentrySpan extends ISentrySpan {
     return json;
   }
 
+  bool _finished = false;
+
   @override
-  bool get finished => _endTimestamp != null;
+  bool get finished => _finished;
 
   @override
   dynamic get throwable => _throwable;

dart/lib/src/sentry_options.dart

@@ -501,6 +501,14 @@ class SentryOptions {
     return tracesSampleRate != null || tracesSampler != null;
   }
 
+  List<PerformanceCollector> get performanceCollectors =>
+      _performanceCollectors;
+  final List<PerformanceCollector> _performanceCollectors = [];
+
+  void addPerformanceCollector(PerformanceCollector collector) {
+    _performanceCollectors.add(collector);
+  }
+
   @internal
   late SentryExceptionFactory exceptionFactory = SentryExceptionFactory(this);
 

dart/lib/src/sentry_tracer.dart

@@ -69,6 +69,7 @@ class SentryTracer extends ISentrySpan {
       _hub,
       samplingDecision: transactionContext.samplingDecision,
       startTimestamp: startTimestamp,
+      isRootSpan: true,
     );
     _waitForChildren = waitForChildren;
     _autoFinishAfter = autoFinishAfter;
@@ -80,6 +81,12 @@ class SentryTracer extends ISentrySpan {
         SentryTransactionNameSource.custom;
     _trimEnd = trimEnd;
     _onFinish = onFinish;
+
+    for (final collector in _hub.options.performanceCollectors) {
+      if (collector is PerformanceContinuousCollector) {
+        collector.onSpanStarted(_rootSpan);
+      }
+    }
   }
 
   @override
@@ -211,11 +218,13 @@ class SentryTracer extends ISentrySpan {
       return NoOpSentrySpan();
     }
 
-    return _rootSpan.startChild(
+    final child = _rootSpan.startChild(
       operation,
       description: description,
       startTimestamp: startTimestamp,
     );
+
+    return child;
   }
 
   ISentrySpan startChildWithParentSpanId(
@@ -256,6 +265,12 @@ class SentryTracer extends ISentrySpan {
 
     _children.add(child);
 
+    for (final collector in _hub.options.performanceCollectors) {
+      if (collector is PerformanceContinuousCollector) {
+        collector.onSpanStarted(child);
+      }
+    }
+
     return child;
   }
 

flutter/example/lib/main.dart

@@ -44,16 +44,15 @@ final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();
 
 Future<void> main() async {
   await setupSentry(
-    () => runApp(
-      SentryWidget(
-        child: DefaultAssetBundle(
-          bundle: SentryAssetBundle(),
-          child: const MyApp(),
-        ),
-      ),
-    ),
-    exampleDsn,
-  );
+      () => runApp(
+            SentryWidget(
+              child: DefaultAssetBundle(
+                bundle: SentryAssetBundle(),
+                child: const MyApp(),
+              ),
+            ),
+          ),
+      exampleDsn);
 }
 
 Future<void> setupSentry(
@@ -96,6 +95,7 @@ Future<void> setupSentry(
         options.environment = 'integration';
         options.beforeSend = beforeSendCallback;
       }
+      options.beforeSend = beforeSendCallback;
     },
     // Init your App.
     appRunner: appRunner,
@@ -420,24 +420,24 @@ class MainScaffold extends StatelessWidget {
 
                 await span.finish(status: const SpanStatus.resourceExhausted());
 
-                await Future.delayed(const Duration(milliseconds: 90));
-
-                final spanChild = span.startChild(
-                  'childOfChildOfMyOp',
-                  description: 'childOfChildOfMyOp span',
-                );
-
-                await Future.delayed(const Duration(milliseconds: 110));
-
-                spanChild.startChild(
-                  'unfinishedChild',
-                  description: 'I wont finish',
-                );
-
-                await spanChild.finish(
-                    status: const SpanStatus.internalError());
-
-                await Future.delayed(const Duration(milliseconds: 50));
+                // await Future.delayed(const Duration(milliseconds: 90));
+                //
+                // final spanChild = span.startChild(
+                //   'childOfChildOfMyOp',
+                //   description: 'childOfChildOfMyOp span',
+                // );
+                //
+                // await Future.delayed(const Duration(milliseconds: 110));
+                //
+                // spanChild.startChild(
+                //   'unfinishedChild',
+                //   description: 'I wont finish',
+                // );
+                //
+                // await spanChild.finish(
+                //     status: const SpanStatus.internalError());
+                //
+                // await Future.delayed(const Duration(milliseconds: 50));
                 // findPrimeNumber(1000000); // Uncomment to see it with profiling
                 await transaction.finish(status: const SpanStatus.ok());
               },

flutter/lib/src/frame_callback_handler.dart

@@ -1,7 +1,11 @@
+import 'package:flutter/cupertino.dart';
 import 'package:flutter/scheduler.dart';
 
 abstract class FrameCallbackHandler {
   void addPostFrameCallback(FrameCallback callback);
+  void addPersistentFrameCallback(FrameCallback callback);
+  Future<void> get endOfFrame;
+  late bool hasScheduledFrame;
 }
 
 class DefaultFrameCallbackHandler implements FrameCallbackHandler {
@@ -12,4 +16,21 @@ class DefaultFrameCallbackHandler implements FrameCallbackHandler {
       SchedulerBinding.instance.addPostFrameCallback(callback);
     } catch (_) {}
   }
+
+  @override
+  void addPersistentFrameCallback(FrameCallback callback) {
+    try {
+      WidgetsBinding.instance.addPersistentFrameCallback(callback);
+    } catch (_) {}
+  }
+
+  @override
+  Future<void> get endOfFrame async {
+    try {
+      await WidgetsBinding.instance.endOfFrame;
+    } catch (_) {}
+  }
+
+  @override
+  bool hasScheduledFrame = true;
 }

flutter/lib/src/sentry_flutter.dart

@@ -4,6 +4,7 @@ import 'dart:ui';
 import 'package:flutter/services.dart';
 import 'package:flutter/widgets.dart';
 import 'package:meta/meta.dart';
+import 'span_frame_metrics_collector.dart';
 import '../sentry_flutter.dart';
 import 'event_processor/android_platform_exception_event_processor.dart';
 import 'event_processor/flutter_exception_event_processor.dart';
@@ -90,6 +91,9 @@ mixin SentryFlutter {
 
     await _initDefaultValues(flutterOptions, channel);
 
+    flutterOptions
+        .addPerformanceCollector(SpanFrameMetricsCollector(flutterOptions));
+
     await Sentry.init(
       (options) => optionsConfiguration(options as SentryFlutterOptions),
       appRunner: appRunner,

flutter/lib/src/sentry_flutter_options.dart

@@ -232,6 +232,20 @@ class SentryFlutterOptions extends SentryOptions {
   /// Read timeout. This will only be synced to the Android native SDK.
   Duration readTimeout = Duration(seconds: 5);
 
+  /// Enable or disable Frames Tracking, which is used to report frame information
+  /// for every [ISentrySpan].
+  ///
+  /// When enabled, the following metrics are reported for each span:
+  /// - Slow frames: The number of frames that exceeded a specified threshold for frame duration.
+  /// - Frozen frames: The number of frames that took an unusually long time to render, indicating a potential freeze or hang.
+  /// - Total frames count: The total number of frames rendered during the span.
+  /// - Frames delay: The delayed frame render duration of all frames.
+
+  /// Read more about frames tracking here: https://develop.sentry.dev/sdk/performance/frames-delay/
+  ///
+  /// Defaults to `true`
+  bool enableFramesTracking = true;
+
   /// By using this, you are disabling native [Breadcrumb] tracking and instead
   /// you are just tracking [Breadcrumb]s which result from events available
   /// in the current Flutter environment.