feat(span-first): add span v2 support for frames tracking

packages/dart/lib/sentry.dart

@@ -42,6 +42,7 @@ export 'src/sentry_envelope.dart';
 export 'src/sentry_envelope_item.dart';
 export 'src/sentry_options.dart';
 export 'src/telemetry/sentry_trace_lifecycle.dart';
+export 'src/telemetry/span/sentry_span_v2.dart';
 // ignore: invalid_export_of_internal_element
 export 'src/sentry_trace_origins.dart';
 export 'src/span_data_convention.dart';

packages/dart/lib/src/constants.dart

@@ -119,6 +119,19 @@ abstract class SemanticAttributesConstants {
   /// The device family (e.g., "iOS", "Android").
   static const deviceFamily = 'device.family';
 
+  /// The number of total frames rendered during the lifetime of the span.
+  static const framesTotal = 'frames.total';
+
+  /// The number of slow frames rendered during the lifetime of the span.
+  static const framesSlow = 'frames.slow';
+
+  /// The number of frozen frames rendered during the lifetime of the span.
+  static const framesFrozen = 'frames.frozen';
+
+  /// The sum of all delayed frame durations in seconds during the lifetime of the span.
+  /// For more information see [frames delay](https://develop.sentry.dev/sdk/performance/frames-delay/).
+  static const framesDelay = 'frames.delay';
+
   /// The HTTP request method (e.g., "GET", "POST").
   static const httpRequestMethod = 'http.request.method';
 

packages/dart/lib/src/hub.dart

@@ -713,6 +713,8 @@ class Hub {
       scope.setActiveSpan(span);
     }
 
+    _options.lifecycleRegistry.dispatchCallback(OnSpanStartV2(span));
+
     return span;
   }
 

packages/dart/lib/src/performance_collector.dart

@@ -11,3 +11,13 @@ abstract class PerformanceContinuousCollector extends PerformanceCollector {
 
   void clear();
 }
+
+/// Used for collecting continuous data about vitals (slow, frozen frames, etc.)
+/// during a span (v2 API).
+abstract class PerformanceContinuousCollectorV2 extends PerformanceCollector {
+  Future<void> onSpanStarted(SentrySpanV2 span);
+
+  Future<void> onSpanFinished(SentrySpanV2 span, DateTime endTimestamp);
+
+  void clear();
+}

packages/dart/lib/src/sdk_lifecycle_hooks.dart

@@ -97,7 +97,16 @@ class OnSpanFinish extends SdkLifecycleEvent {
   final ISentrySpan span;
 }
 
-/// Dispatched when span is ready for processing (before default enrichment).
+/// Dispatched when a sampled span is started.
+@internal
+class OnSpanStartV2 extends SdkLifecycleEvent {
+  OnSpanStartV2(this.span);
+
+  final SentrySpanV2 span;
+}
+
+/// Dispatched when a span has been captured and is ready for processing (before default enrichment)
+/// and before it's being added to the telemetry processor.
 ///
 /// This is useful for integrations to hook into e.g for enriching with attributes.
 @internal
@@ -107,6 +116,8 @@ class OnProcessSpan extends SdkLifecycleEvent {
   OnProcessSpan(this.span);
 }
 
+/// Dispatched when a metric has been captured and is ready for processing (before default enrichment)
+/// and before it's being added to the telemetry processor.
 @internal
 class OnProcessMetric extends SdkLifecycleEvent {
   final SentryMetric metric;

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

@@ -23,6 +23,9 @@ final class NoOpSentrySpanV2 implements SentrySpanV2 {
   @override
   SentrySpanV2? get parentSpan => null;
 
+  @override
+  DateTime get startTimestamp => DateTime.fromMillisecondsSinceEpoch(0);
+
   @override
   DateTime? get endTimestamp => null;
 

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

@@ -117,6 +117,9 @@ final class RecordingSentrySpanV2 implements SentrySpanV2 {
   @override
   set status(SentrySpanStatusV2 value) => _status = value;
 
+  @override
+  DateTime get startTimestamp => _startTimestamp;
+
   @override
   DateTime? get endTimestamp => _endTimestamp;
 

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

@@ -32,7 +32,12 @@ sealed class SentrySpanV2 {
   /// Sets the status of this span.
   set status(SentrySpanStatusV2 status);
 
+  /// The start timestamp of this span.
+  DateTime get startTimestamp;
+
   /// The end timestamp of this span.
+  ///
+  /// Returns null if the span has not ended yet.
   DateTime? get endTimestamp;
 
   /// Whether this span has ended.

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

@@ -26,6 +26,9 @@ final class UnsetSentrySpanV2 implements SentrySpanV2 {
   @override
   SentrySpanV2? get parentSpan => _throw();
 
+  @override
+  DateTime get startTimestamp => _throw();
+
   @override
   DateTime? get endTimestamp => _throw();
 

packages/flutter/lib/src/frames_tracking/span_frame_metrics_collector_v2.dart

@@ -0,0 +1,95 @@
+// ignore_for_file: invalid_use_of_internal_member
+
+import 'package:meta/meta.dart';
+
+import '../../sentry_flutter.dart';
+import '../utils/internal_logger.dart';
+import 'sentry_delayed_frames_tracker.dart';
+
+/// Collects frames from [SentryDelayedFramesTracker], calculates the metrics
+/// and attaches them to spans.
+@internal
+class SpanFrameMetricsCollectorV2 implements PerformanceContinuousCollectorV2 {
+  SpanFrameMetricsCollectorV2(
+    this._frameTracker, {
+    required void Function() resumeFrameTracking,
+    required void Function() pauseFrameTracking,
+  })  : _resumeFrameTracking = resumeFrameTracking,
+        _pauseFrameTracking = pauseFrameTracking;
+
+  final SentryDelayedFramesTracker _frameTracker;
+  final void Function() _resumeFrameTracking;
+  final void Function() _pauseFrameTracking;
+
+  /// Stores the spans that are actively being tracked.
+  /// After the frames are calculated and stored in the span the span is removed from this list.
+  @visibleForTesting
+  final List<SentrySpanV2> activeSpans = [];
+
+  @override
+  Future<void> onSpanStarted(SentrySpanV2 span) async {
+    return _tryCatch('onSpanStarted', () async {
+      if (span is NoOpSentrySpan) {
+        return;
+      }
+
+      activeSpans.add(span);
+      _resumeFrameTracking();
+    });
+  }
+
+  @override
+  Future<void> onSpanFinished(SentrySpanV2 span, DateTime endTimestamp) async {
+    return _tryCatch('onSpanFinished', () async {
+      if (span is NoOpSentrySpan) {
+        return;
+      }
+
+      final startTimestamp = span.startTimestamp;
+      final metrics = _frameTracker.getFrameMetrics(
+          spanStartTimestamp: startTimestamp, spanEndTimestamp: endTimestamp);
+
+      if (metrics != null) {
+        final attributes = Map<String, SentryAttribute>.from(span.attributes);
+        attributes.putIfAbsent(SemanticAttributesConstants.framesTotal,
+            () => SentryAttribute.int(metrics.totalFrameCount));
+        attributes.putIfAbsent(SemanticAttributesConstants.framesSlow,
+            () => SentryAttribute.int(metrics.slowFrameCount));
+        attributes.putIfAbsent(SemanticAttributesConstants.framesFrozen,
+            () => SentryAttribute.int(metrics.frozenFrameCount));
+        attributes.putIfAbsent(SemanticAttributesConstants.framesDelay,
+            () => SentryAttribute.int(metrics.framesDelay));
+        span.setAttributes(attributes);
+      }
+
+      activeSpans.remove(span);
+      if (activeSpans.isEmpty) {
+        clear();
+      } else {
+        _frameTracker.removeIrrelevantFrames(activeSpans.first.startTimestamp);
+      }
+    });
+  }
+
+  Future<void> _tryCatch(String methodName, Future<void> Function() fn) async {
+    try {
+      return fn();
+    } catch (exception, stackTrace) {
+      internalLogger.error(
+        'SpanV2FrameMetricsCollector $methodName failed',
+        error: exception,
+        stackTrace: stackTrace,
+      );
+      clear();
+    }
+  }
+
+  @override
+  void clear() {
+    _pauseFrameTracking();
+    _frameTracker.clear();
+    activeSpans.clear();
+    // we don't need to clear the expected frame duration as that realistically
+    // won't change throughout the application's lifecycle
+  }
+}

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

@@ -6,6 +6,7 @@ import '../../sentry_flutter.dart';
 import '../binding_wrapper.dart';
 import '../frames_tracking/sentry_delayed_frames_tracker.dart';
 import '../frames_tracking/span_frame_metrics_collector.dart';
+import '../frames_tracking/span_frame_metrics_collector_v2.dart';
 import '../native/sentry_native_binding.dart';
 
 class FramesTrackingIntegration implements Integration<SentryFlutterOptions> {
@@ -50,11 +51,29 @@ class FramesTrackingIntegration implements Integration<SentryFlutterOptions> {
         SentryDelayedFramesTracker(options, expectedFrameDuration);
     widgetsBinding.initializeFramesTracking(
         framesTracker.addDelayedFrame, options, expectedFrameDuration);
-    final collector = SpanFrameMetricsCollector(options, framesTracker,
-        resumeFrameTracking: () => widgetsBinding.resumeTrackingFrames(),
-        pauseFrameTracking: () => widgetsBinding.pauseTrackingFrames());
-    options.addPerformanceCollector(collector);
-    _collector = collector;
+    switch (options.traceLifecycle) {
+      case SentryTraceLifecycle.streaming:
+        final collector = SpanFrameMetricsCollectorV2(framesTracker,
+            resumeFrameTracking: () => widgetsBinding.resumeTrackingFrames(),
+            pauseFrameTracking: () => widgetsBinding.pauseTrackingFrames());
+        _collector = collector;
+
+        options.lifecycleRegistry.registerCallback<OnSpanStartV2>((event) {
+          collector.onSpanStarted(event.span);
+        });
+
+        options.lifecycleRegistry.registerCallback<OnProcessSpan>((event) {
+          if (event.span.endTimestamp != null) {
+            collector.onSpanFinished(event.span, event.span.endTimestamp!);
+          }
+        });
+      case SentryTraceLifecycle.static:
+        final collector = SpanFrameMetricsCollector(options, framesTracker,
+            resumeFrameTracking: () => widgetsBinding.resumeTrackingFrames(),
+            pauseFrameTracking: () => widgetsBinding.pauseTrackingFrames());
+        options.addPerformanceCollector(collector);
+        _collector = collector;
+    }
 
     options.sdk.addIntegration(integrationName);
     options.log(SentryLevel.debug,