[Structured Logs]: Buffering and Flushing of Logs (#2930)

Author: denrase

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Logs: Models & Envelopes ([#2916](https://github.com/getsentry/sentry-dart/pull/2916))
 - Logs: Integrate in Sentry Client ([#2920](https://github.com/getsentry/sentry-dart/pull/2920))
+- [Structured Logs]: Buffering and Flushing of Logs ([#2930](https://github.com/getsentry/sentry-dart/pull/2930))
 
 ## 9.0.0-beta.2
 

dart/lib/src/noop_log_batcher.dart

@@ -0,0 +1,12 @@
+import 'dart:async';
+
+import 'sentry_log_batcher.dart';
+import 'protocol/sentry_log.dart';
+
+class NoopLogBatcher implements SentryLogBatcher {
+  @override
+  FutureOr<void> addLog(SentryLog log) {}
+
+  @override
+  Future<void> flush() async {}
+}

dart/lib/src/sentry_client.dart

@@ -27,6 +27,7 @@ import 'type_check_hint.dart';
 import 'utils/isolate_utils.dart';
 import 'utils/regex_utils.dart';
 import 'utils/stacktrace_utils.dart';
+import 'sentry_log_batcher.dart';
 import 'version.dart';
 
 /// Default value for [SentryUser.ipAddress]. It gets set when an event does not have
@@ -75,6 +76,9 @@ class SentryClient {
     if (enableFlutterSpotlight) {
       options.transport = SpotlightHttpTransport(options, options.transport);
     }
+    if (options.enableLogs) {
+      options.logBatcher = SentryLogBatcher(options);
+    }
     return SentryClient._(options);
   }
 
@@ -528,9 +532,12 @@ class SentryClient {
     SentryLog? processedLog = log;
     if (beforeSendLog != null) {
       try {
-        processedLog = beforeSendLog(log);
-        if (processedLog == null) {
-          return;
+        final callbackResult = beforeSendLog(log);
+
+        if (callbackResult is Future<SentryLog?>) {
+          processedLog = await callbackResult;
+        } else {
+          processedLog = callbackResult;
         }
       } catch (exception, stackTrace) {
         _options.logger(
@@ -544,15 +551,9 @@ class SentryClient {
         }
       }
     }
-
-    // TODO: Batch in separate PR, so we can send multiple logs at once.
-    final envelope = SentryEnvelope.fromLogs(
-      [processedLog ?? log],
-      _options.sdk,
-    );
-
-    // TODO: Make sure the Android SDK understands the log envelope type.
-    await captureEnvelope(envelope);
+    if (processedLog != null) {
+      _options.logBatcher.addLog(processedLog);
+    }
   }
 
   void close() {

dart/lib/src/sentry_log_batcher.dart

@@ -0,0 +1,52 @@
+import 'dart:async';
+import 'sentry_envelope.dart';
+import 'sentry_options.dart';
+import 'protocol/sentry_log.dart';
+import 'package:meta/meta.dart';
+
+@internal
+class SentryLogBatcher {
+  SentryLogBatcher(this._options, {Duration? flushTimeout, int? maxBufferSize})
+      : _flushTimeout = flushTimeout ?? Duration(seconds: 5),
+        _maxBufferSize = maxBufferSize ?? 100;
+
+  final SentryOptions _options;
+  final Duration _flushTimeout;
+  final int _maxBufferSize;
+
+  final _logBuffer = <SentryLog>[];
+
+  Timer? _flushTimer;
+
+  void addLog(SentryLog log) {
+    _logBuffer.add(log);
+
+    _flushTimer?.cancel();
+
+    if (_logBuffer.length >= _maxBufferSize) {
+      return flush();
+    } else {
+      _flushTimer = Timer(_flushTimeout, flush);
+    }
+  }
+
+  void flush() {
+    _flushTimer?.cancel();
+    _flushTimer = null;
+
+    final logs = List<SentryLog>.from(_logBuffer);
+    _logBuffer.clear();
+
+    if (logs.isEmpty) {
+      return;
+    }
+
+    final envelope = SentryEnvelope.fromLogs(
+      logs,
+      _options.sdk,
+    );
+
+    // TODO: Make sure the Android SDK understands the log envelope type.
+    _options.transport.send(envelope);
+  }
+}

dart/lib/src/sentry_options.dart

@@ -15,6 +15,8 @@ import 'sentry_exception_factory.dart';
 import 'sentry_stack_trace_factory.dart';
 import 'transport/noop_transport.dart';
 import 'version.dart';
+import 'sentry_log_batcher.dart';
+import 'noop_log_batcher.dart';
 
 // TODO: shutdownTimeout, flushTimeoutMillis
 // https://api.dart.dev/stable/2.10.2/dart-io/HttpClient/close.html doesn't have a timeout param, we'd need to implement manually
@@ -540,6 +542,9 @@ class SentryOptions {
   /// Disabled by default.
   bool enableLogs = false;
 
+  @internal
+  SentryLogBatcher logBatcher = NoopLogBatcher();
+
   SentryOptions({String? dsn, Platform? platform, RuntimeChecker? checker}) {
     this.dsn = dsn;
     if (platform != null) {
@@ -671,7 +676,7 @@ typedef BeforeMetricCallback = bool Function(
 
 /// This function is called right before a log is about to be sent.
 /// Can return a modified log or null to drop the log.
-typedef BeforeSendLogCallback = SentryLog? Function(SentryLog log);
+typedef BeforeSendLogCallback = FutureOr<SentryLog?> Function(SentryLog log);
 
 /// Used to provide timestamp for logging.
 typedef ClockProvider = DateTime Function();

dart/test/mocks/mock_log_batcher.dart

@@ -0,0 +1,19 @@
+import 'dart:async';
+
+import 'package:sentry/src/protocol/sentry_log.dart';
+import 'package:sentry/src/sentry_log_batcher.dart';
+
+class MockLogBatcher implements SentryLogBatcher {
+  final addLogCalls = <SentryLog>[];
+  final flushCalls = <void>[];
+
+  @override
+  FutureOr<void> addLog(SentryLog log) {
+    addLogCalls.add(log);
+  }
+
+  @override
+  Future<void> flush() async {
+    flushCalls.add(null);
+  }
+}