Logging Integration

sentry_logging/.gitignore

@@ -0,0 +1,10 @@
+# Files and directories created by pub.
+.dart_tool/
+.packages
+
+# Conventional directory for build outputs.
+build/
+
+# Omit committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock

sentry_logging/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+- Initial version.

sentry_logging/README.md

@@ -0,0 +1 @@
+# WIP

sentry_logging/analysis_options.yaml

@@ -0,0 +1,32 @@
+include: package:lints/recommended.yaml
+
+analyzer:
+  strong-mode:
+    implicit-casts: false
+    implicit-dynamic: false
+  language:
+    strict-raw-types: true
+  errors:
+    # treat missing required parameters as a warning (not a hint)
+    missing_required_param: error
+    # treat missing returns as a warning (not a hint)
+    missing_return: error
+    # allow having TODOs in the code
+    todo: ignore
+    # allow self-reference to deprecated members (we do this because otherwise we have
+    # to annotate every member in every test, assert, etc, when we deprecate something)
+    deprecated_member_use_from_same_package: warning
+    # ignore sentry/path on pubspec as we change it on deployment
+    invalid_dependency: ignore
+  exclude:
+    - example/**
+
+linter:
+  rules:
+    - prefer_final_locals
+    - public_member_api_docs
+    - prefer_single_quotes
+    - prefer_relative_imports
+    - unnecessary_brace_in_string_interps
+    - implementation_imports
+    - require_trailing_commas

sentry_logging/example/sentry_logging_example.dart

@@ -0,0 +1,34 @@
+import 'package:sentry_logging/sentry_logging.dart';
+import 'dart:async';
+import 'package:sentry/sentry.dart';
+import 'package:logging/logging.dart';
+
+Future<void> main() async {
+  // ATTENTION: Change the DSN below with your own to see the events in Sentry. Get one at sentry.io
+  const dsn =
+      'https://[email protected]/5428562';
+
+  await Sentry.init(
+    (options) {
+      options.dsn = dsn;
+      options.addIntegration(LoggingIntegration());
+    },
+    appRunner: runApp,
+  );
+}
+
+Future<void> runApp() async {
+  final log = Logger('MyAwesomeLogger');
+
+  log.warning('a warning!');
+
+  try {
+    throw Exception();
+  } catch (error, stackTrace) {
+    // The log from above will be contained in this crash report.
+    await Sentry.captureException(
+      error,
+      stackTrace: stackTrace,
+    );
+  }
+}

sentry_logging/lib/sentry_logging.dart

@@ -0,0 +1,3 @@
+library sentry_logging;
+
+export 'src/logging_integration.dart';

sentry_logging/lib/src/extension.dart

@@ -0,0 +1,54 @@
+// ignore_for_file: public_member_api_docs
+
+import 'package:logging/logging.dart';
+import 'package:sentry/sentry.dart';
+import 'package:sentry/sentry_io.dart';
+
+extension LogRecordX on LogRecord {
+  Breadcrumb toBreadcrumb() {
+    return Breadcrumb(
+      category: 'log',
+      type: 'debug',
+      timestamp: time,
+      level: level.toSentryLevel(),
+      message: message,
+      data: <String, Object>{
+        if (object != null) 'LogRecord.object': object!.toString(),
+        if (error != null) 'LogRecord.error': error!.toString(),
+        if (stackTrace != null) 'LogRecord.stackTrace': stackTrace!.toString(),
+        'LogRecord.loggerName': loggerName,
+        'LogRecord.sequenceNumber': sequenceNumber,
+      },
+    );
+  }
+
+  SentryEvent toEvent() {
+    return SentryEvent(
+      logger: loggerName,
+      level: level.toSentryLevel(),
+      message: SentryMessage(message),
+      throwable: error,
+      extra: <String, Object>{
+        if (object != null) 'LogRecord.object': object!,
+        'LogRecord.sequenceNumber': sequenceNumber,
+      },
+    );
+  }
+}
+
+extension LogLevelX on Level {
+  SentryLevel? toSentryLevel() {
+    return <Level, SentryLevel?>{
+      Level.ALL: SentryLevel.debug,
+      Level.FINEST: SentryLevel.debug,
+      Level.FINER: SentryLevel.debug,
+      Level.FINE: SentryLevel.debug,
+      Level.CONFIG: SentryLevel.debug,
+      Level.INFO: SentryLevel.info,
+      Level.WARNING: SentryLevel.warning,
+      Level.SEVERE: SentryLevel.error,
+      Level.SHOUT: SentryLevel.fatal,
+      Level.OFF: null,
+    }[this];
+  }
+}

sentry_logging/lib/src/logging_integration.dart

@@ -0,0 +1,58 @@
+import 'dart:async';
+
+import 'package:logging/logging.dart';
+import 'package:sentry/sentry.dart';
+import 'extension.dart';
+
+/// An [Integration] which listens to all messages of the
+/// [logging](https://pub.dev/packages/logging) package.
+class LoggingIntegration extends Integration<SentryOptions> {
+  /// Creates the [LoggingIntegration].
+  ///
+  /// Setting [logExceptionAsEvent] to true (default) captures all
+  /// messages with errors as an [SentryEvent] instead of an [Breadcrumb].
+  /// Setting [logExceptionAsEvent] to false captures everything as
+  /// [Breadcrumb]s.
+  LoggingIntegration({bool logExceptionAsEvent = true})
+      : _logExceptionsAsEvents = logExceptionAsEvent;
+
+  final bool _logExceptionsAsEvents;
+  late StreamSubscription<LogRecord> _subscription;
+  late Hub _hub;
+
+  @override
+  FutureOr<void> call(Hub hub, SentryOptions options) {
+    _hub = hub;
+    _subscription = Logger.root.onRecord.listen(
+      _onLog,
+      onError: (Object error, StackTrace stackTrace) {
+        _hub.captureException(error, stackTrace: stackTrace);
+      },
+    );
+    options.sdk.addIntegration('LoggingIntegration');
+  }
+
+  @override
+  Future<void> close() async {
+    await super.close();
+    await _subscription.cancel();
+  }
+
+  void _onLog(LogRecord record) {
+    // Everything is just logged as a breadcrumb
+    if (!_logExceptionsAsEvents) {
+      _hub.addBreadcrumb(record.toBreadcrumb());
+      return;
+    }
+
+    // If a LogRecord contains an exception, it gets reported as an SentryEvent
+    if (record.error == null) {
+      _hub.addBreadcrumb(record.toBreadcrumb());
+    } else {
+      _hub.captureEvent(
+        record.toEvent(),
+        stackTrace: record.stackTrace,
+      );
+    }
+  }
+}

sentry_logging/pubspec.yaml

@@ -0,0 +1,16 @@
+name: sentry_logging
+description: An integration which adds support for recording log from the logging package.
+version: 1.0.0
+homepage: https://docs.sentry.io/platforms/flutter/
+repository: https://github.com/getsentry/sentry-dart
+
+environment:
+  sdk: '>=2.14.4 <3.0.0'
+
+dependencies:
+  logging: ^1.0.0
+  sentry: ^6.1.0
+
+dev_dependencies:
+  lints: ^1.0.0
+  test: ^1.16.0

sentry_logging/test/logging_integration_test.dart

@@ -0,0 +1,97 @@
+import 'package:logging/logging.dart';
+import 'package:sentry/sentry.dart';
+import 'package:sentry_logging/sentry_logging.dart';
+import 'package:test/expect.dart';
+import 'package:test/scaffolding.dart';
+
+import 'mock_hub.dart';
+
+void main() {
+  late Fixture fixture;
+  setUp(() {
+    fixture = Fixture();
+  });
+
+  test('options.sdk.integrations contains $LoggingIntegration', () async {
+    final sut = fixture.createSut();
+    await sut.call(fixture.hub, fixture.options);
+    await sut.close();
+    expect(
+      fixture.options.sdk.integrations.contains('LoggingIntegration'),
+      true,
+    );
+  });
+
+  test('logger gets recorded', () async {
+    final sut = fixture.createSut();
+    await sut.call(fixture.hub, fixture.options);
+
+    final log = Logger('FooBarLogger');
+    log.warning(
+      'A log message',
+    );
+
+    expect(fixture.hub.events.length, 0);
+    expect(fixture.hub.breadcrumbs.length, 1);
+    final crumb = fixture.hub.breadcrumbs.first;
+    expect(crumb.level, SentryLevel.warning);
+    expect(crumb.message, 'A log message');
+    expect(crumb.data, <String, dynamic>{
+      'LogRecord.loggerName': 'FooBarLogger',
+      'LogRecord.sequenceNumber': 0,
+    });
+    expect(crumb.timestamp, isNotNull);
+    expect(crumb.category, 'log');
+    expect(crumb.type, 'debug');
+  });
+
+  test('exceptions is recorded as breadcrumb if logExceptionsAsEvents = false',
+      () async {
+    final sut = fixture.createSut(logExceptionsAsEvents: false);
+    await sut.call(fixture.hub, fixture.options);
+
+    final log = Logger('FooBarLogger');
+    log.warning(
+      'A log message',
+      Exception('foo bar'),
+      StackTrace.current,
+    );
+    expect(fixture.hub.events.length, 0);
+    expect(fixture.hub.breadcrumbs.length, 1);
+    final crumb = fixture.hub.breadcrumbs.first;
+    expect(crumb.data?.length, 4);
+  });
+
+  test('exceptions is recorded as event if logExceptionsAsEvents = true',
+      () async {
+    final sut = fixture.createSut(logExceptionsAsEvents: true);
+    await sut.call(fixture.hub, fixture.options);
+
+    final exception = Exception('foo bar');
+    final stackTrace = StackTrace.current;
+
+    final log = Logger('FooBarLogger');
+    log.warning(
+      'A log message',
+      exception,
+      stackTrace,
+    );
+    expect(fixture.hub.breadcrumbs.length, 0);
+    expect(fixture.hub.events.length, 1);
+    final event = fixture.hub.events.first.event;
+    expect(event.level, SentryLevel.warning);
+    expect(event.logger, 'FooBarLogger');
+    expect(event.throwable, exception);
+    expect(event.extra?['LogRecord.sequenceNumber'], isNotNull);
+    expect(fixture.hub.events.first.stackTrace, stackTrace);
+  });
+}
+
+class Fixture {
+  SentryOptions options = SentryOptions(dsn: fakeDsn);
+  MockHub hub = MockHub();
+
+  LoggingIntegration createSut({bool logExceptionsAsEvents = true}) {
+    return LoggingIntegration(logExceptionAsEvent: logExceptionsAsEvents);
+  }
+}