Add debounce to capturing screenshots (#2368)

Author: denrase

CHANGELOG.md

@@ -33,6 +33,22 @@
   ```  
 - Linux native error & obfuscation support ([#2431](https://github.com/getsentry/sentry-dart/pull/2431))
 - Improve Device context on plain Dart and Flutter desktop apps ([#2441](https://github.com/getsentry/sentry-dart/pull/2441))
+- Add debounce to capturing screenshots ([#2368](https://github.com/getsentry/sentry-dart/pull/2368))
+  - Per default, screenshots are debounced for 2 seconds.
+  - If you need more granular screenshots, you can opt out of debouncing:
+  ```dart
+  await SentryFlutter.init((options) {
+    options.beforeCaptureScreenshot = (event, hint, debounce) {
+      if (debounce) {
+        return true; // Capture screenshot even if the SDK wants to debounce it.
+      } else {
+        // check event and hint
+        ...
+      }
+    };
+  });
+  ```
+  - Replace deprecated `BeforeScreenshotCallback` with new `BeforeCaptureCallback`.
 
 ### Fixes
 

flutter/lib/src/event_processor/screenshot_event_processor.dart

@@ -9,14 +9,16 @@ import '../screenshot/recorder.dart';
 import '../screenshot/recorder_config.dart';
 import 'package:flutter/widgets.dart' as widget;
 
+import '../utils/debouncer.dart';
+
 class ScreenshotEventProcessor implements EventProcessor {
   final SentryFlutterOptions _options;
 
   late final ScreenshotRecorder _recorder;
+  late final Debouncer _debouncer;
 
   ScreenshotEventProcessor(this._options) {
     final targetResolution = _options.screenshotQuality.targetResolution();
-
     _recorder = ScreenshotRecorder(
       ScreenshotRecorderConfig(
         width: targetResolution,
@@ -25,6 +27,11 @@ class ScreenshotEventProcessor implements EventProcessor {
       _options,
       isReplayRecorder: false,
     );
+    _debouncer = Debouncer(
+      // ignore: invalid_use_of_internal_member
+      _options.clock,
+      waitTimeMs: 2000,
+    );
   }
 
   @override
@@ -43,29 +50,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.beforeCaptureScreenshot;
+
+    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;
       }
     }
 
@@ -88,8 +117,7 @@ class ScreenshotEventProcessor implements EventProcessor {
       return event;
     }
 
-    Uint8List? screenshotData = await createScreenshot();
-
+    final screenshotData = await createScreenshot();
     if (screenshotData != null) {
       hint.screenshot = SentryAttachment.fromScreenshotData(screenshotData);
     }

flutter/lib/src/integrations/screenshot_integration.dart

@@ -3,7 +3,7 @@ import '../event_processor/screenshot_event_processor.dart';
 import '../sentry_flutter_options.dart';
 
 /// Adds [ScreenshotEventProcessor] to options event processors if
-/// [SentryFlutterOptions.screenshot.attach] is true
+/// [SentryFlutterOptions.attachScreenshot] is true
 class ScreenshotIntegration implements Integration<SentryFlutterOptions> {
   SentryFlutterOptions? _options;
   ScreenshotEventProcessor? _screenshotEventProcessor;

flutter/lib/src/sentry_flutter_options.dart

@@ -196,10 +196,14 @@ class SentryFlutterOptions extends SentryOptions {
   /// See https://docs.sentry.io/platforms/flutter/troubleshooting/#screenshot-integration-background-crash
   bool attachScreenshotOnlyWhenResumed = false;
 
+  @Deprecated(
+      'Will be removed in a future version. Use [beforeCaptureScreenshot] 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? beforeCaptureScreenshot;
 
   /// Enable or disable automatic breadcrumbs for User interactions Using [Listener]
   ///
@@ -417,9 +421,34 @@ class _SentryFlutterExperimentalOptions {
       _privacy ?? SentryPrivacyOptions();
 }
 
-/// 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;