Add debounce to capturing screenshots

CHANGELOG.md

@@ -10,7 +10,9 @@
     - SDK creates a synthetic trace using `StackTrace.current`
     - Internal SDK frames are removed to reduce noise
   - Original stack traces (when provided) are left unchanged
-
+- Add debounce to `ScreenshotWidget` ([#2368](https://github.com/getsentry/sentry-dart/pull/2368))
+  - Replace deprecated `BeforeScreenshotCallback` with new `BeforeCaptureCallback`.
+
 ### Features
 
 - Improve frame tracking accuracy ([#2372](https://github.com/getsentry/sentry-dart/pull/2372))

flutter/lib/src/event_processor/screenshot_event_processor.dart

@@ -11,10 +11,18 @@ import '../sentry_flutter_options.dart';
 import '../renderer/renderer.dart';
 import 'package:flutter/widgets.dart' as widget;
 
+import '../utils/debouncer.dart';
+
 class ScreenshotEventProcessor implements EventProcessor {
   final SentryFlutterOptions _options;
+  final Debouncer _debouncer;
 
-  ScreenshotEventProcessor(this._options);
+  ScreenshotEventProcessor(this._options)
+      : _debouncer = Debouncer(
+          // ignore: invalid_use_of_internal_member
+          _options.clock,
+          waitTimeMs: 2000,
+        );
 
   @override
   Future<SentryEvent?> apply(SentryEvent event, Hint hint) async {
@@ -32,29 +40,51 @@ class ScreenshotEventProcessor implements EventProcessor {
       return event; // No need to attach screenshot of feedback form.
     }
 
+    // skip capturing in case of debouncing (=too many frequent capture requests)
+    // the BeforeCaptureCallback may overrules the debouncing decision
+    final shouldDebounce = _debouncer.shouldDebounce();
+
+    // ignore: deprecated_member_use_from_same_package
     final beforeScreenshot = _options.beforeScreenshot;
-    if (beforeScreenshot != null) {
-      try {
-        final result = beforeScreenshot(event, hint: hint);
-        bool takeScreenshot;
+    final beforeCapture = _options.beforeCapture;
+
+    try {
+      FutureOr<bool>? result;
+
+      if (beforeCapture != null) {
+        result = beforeCapture(event, hint, shouldDebounce);
+      } else if (beforeScreenshot != null) {
+        result = beforeScreenshot(event, hint: hint);
+      }
+
+      bool takeScreenshot = true;
+
+      if (result != null) {
         if (result is Future<bool>) {
           takeScreenshot = await result;
         } else {
           takeScreenshot = result;
         }
-        if (!takeScreenshot) {
-          return event;
-        }
-      } catch (exception, stackTrace) {
+      } else if (shouldDebounce) {
         _options.logger(
-          SentryLevel.error,
-          'The beforeScreenshot callback threw an exception',
-          exception: exception,
-          stackTrace: stackTrace,
+          SentryLevel.debug,
+          'Skipping screenshot capture due to debouncing (too many captures within ${_debouncer.waitTimeMs}ms)',
         );
-        if (_options.automatedTestMode) {
-          rethrow;
-        }
+        takeScreenshot = false;
+      }
+
+      if (!takeScreenshot) {
+        return event;
+      }
+    } catch (exception, stackTrace) {
+      _options.logger(
+        SentryLevel.error,
+        'The beforeCapture/beforeScreenshot callback threw an exception',
+        exception: exception,
+        stackTrace: stackTrace,
+      );
+      if (_options.automatedTestMode) {
+        rethrow;
       }
     }
 

flutter/lib/src/sentry_flutter_options.dart

@@ -195,10 +195,14 @@ class SentryFlutterOptions extends SentryOptions {
   /// Only attach a screenshot when the app is resumed.
   bool attachScreenshotOnlyWhenResumed = false;
 
+  @Deprecated(
+      'Will be removed in a future version. Use [beforeCapture] instead')
+  BeforeScreenshotCallback? beforeScreenshot;
+
   /// Sets a callback which is executed before capturing screenshots. Only
   /// relevant if `attachScreenshot` is set to true. When false is returned
   /// from the function, no screenshot will be attached.
-  BeforeScreenshotCallback? beforeScreenshot;
+  BeforeCaptureCallback? beforeCapture;
 
   /// Enable or disable automatic breadcrumbs for User interactions Using [Listener]
   ///
@@ -387,9 +391,34 @@ class _SentryFlutterExperimentalOptions {
   final replay = SentryReplayOptions();
 }
 
-/// Callback being executed in [ScreenshotEventProcessor], deciding if a
-/// screenshot should be recorded and attached.
-typedef BeforeScreenshotCallback = FutureOr<bool> Function(
-  SentryEvent event, {
-  Hint? hint,
-});
+@Deprecated(
+    'Will be removed in a future version. Use [BeforeCaptureCallback] instead')
+typedef BeforeScreenshotCallback = FutureOr<bool> Function(SentryEvent event,
+    {Hint? hint});
+
+/// A callback which can be used to suppress capturing of screenshots.
+/// It's called in [ScreenshotEventProcessor] if screenshots are enabled.
+/// This gives more fine-grained control over when capturing should be performed,
+/// e.g., only capture screenshots for fatal events or override any debouncing for important events.
+///
+/// Since capturing can be resource-intensive, the debounce parameter should be respected if possible.
+///
+/// Example:
+/// ```dart
+/// if (debounce) {
+///   return false;
+/// } else {
+///   // check event and hint
+/// }
+/// ```
+///
+/// [event] is the event to be checked.
+/// [hint] provides additional hints.
+/// [debounce] indicates if capturing is marked for being debounced.
+///
+/// Returns `true` if capturing should be performed, otherwise `false`.
+typedef BeforeCaptureCallback = FutureOr<bool> Function(
+  SentryEvent event,
+  Hint hint,
+  bool debounce,
+);

flutter/lib/src/utils/debouncer.dart

@@ -1,20 +1,24 @@
-import 'dart:async';
-import 'package:flutter/foundation.dart';
 import 'package:meta/meta.dart';
+import 'package:sentry/sentry.dart';
 
 @internal
 class Debouncer {
-  final int milliseconds;
-  Timer? _timer;
+  final ClockProvider clockProvider;
+  final int waitTimeMs;
+  DateTime? _lastExecutionTime;
 
-  Debouncer({required this.milliseconds});
+  Debouncer(this.clockProvider, {this.waitTimeMs = 2000});
 
-  void run(VoidCallback action) {
-    _timer?.cancel();
-    _timer = Timer(Duration(milliseconds: milliseconds), action);
-  }
+  bool shouldDebounce() {
+    final currentTime = clockProvider();
+    final lastExecutionTime = _lastExecutionTime;
+    _lastExecutionTime = currentTime;
+
+    if (lastExecutionTime != null &&
+        currentTime.difference(lastExecutionTime).inMilliseconds < waitTimeMs) {
+      return true;
+    }
 
-  void dispose() {
-    _timer?.cancel();
+    return false;
   }
 }

flutter/lib/src/utils/timer_debouncer.dart

@@ -0,0 +1,20 @@
+import 'dart:async';
+import 'package:flutter/foundation.dart';
+import 'package:meta/meta.dart';
+
+@internal
+class TimerDebouncer {
+  final int milliseconds;
+  Timer? _timer;
+
+  TimerDebouncer({required this.milliseconds});
+
+  void run(VoidCallback action) {
+    _timer?.cancel();
+    _timer = Timer(Duration(milliseconds: milliseconds), action);
+  }
+
+  void dispose() {
+    _timer?.cancel();
+  }
+}

flutter/lib/src/widgets_binding_observer.dart

@@ -3,8 +3,8 @@ import 'dart:ui';
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
+import 'utils/timer_debouncer.dart';
 import '../sentry_flutter.dart';
-import 'utils/debouncer.dart';
 
 /// This is a `WidgetsBindingObserver` which can observe some events of a
 /// Flutter application.
@@ -25,7 +25,8 @@ class SentryWidgetsBindingObserver with WidgetsBindingObserver {
     required SentryFlutterOptions options,
   })  : _hub = hub ?? HubAdapter(),
         _options = options,
-        _screenSizeStreamController = StreamController(sync: true) {
+        _screenSizeStreamController = StreamController(sync: true),
+        _didChangeMetricsDebouncer = TimerDebouncer(milliseconds: 100) {
     if (_options.enableWindowMetricBreadcrumbs) {
       _screenSizeStreamController.stream
           .map(
@@ -47,12 +48,11 @@ class SentryWidgetsBindingObserver with WidgetsBindingObserver {
 
   final Hub _hub;
   final SentryFlutterOptions _options;
+  final TimerDebouncer _didChangeMetricsDebouncer;
 
   // ignore: deprecated_member_use
   final StreamController<SingletonFlutterWindow?> _screenSizeStreamController;
 
-  final _didChangeMetricsDebouncer = Debouncer(milliseconds: 100);
-
   /// This method records lifecycle events.
   /// It tries to mimic the behavior of ActivityBreadcrumbsIntegration of Sentry
   /// Android for lifecycle events.
@@ -91,7 +91,6 @@ class SentryWidgetsBindingObserver with WidgetsBindingObserver {
     if (!_options.enableWindowMetricBreadcrumbs) {
       return;
     }
-
     _didChangeMetricsDebouncer.run(() {
       // ignore: deprecated_member_use
       final window = _options.bindingUtils.instance?.window;