Feat/dart default integrations (#187)

Author: rxlabz

CHANGELOG.md

@@ -4,8 +4,12 @@
 
 - Fix: StackTrace frames with 'package' uri.scheme are inApp by default #185
 - Enhancement: add loadContextsIntegration tests
-- StackTrace factory : package are inApp by default 
 - Fix: missing app's stack traces for Flutter errors
+- Enhancement: add isolateErrorIntegration and runZonedGuardedIntegration to default integrations in sentry-dart
+
+### Breaking changes
+
+- `Sentry.init` and `SentryFlutter.init` have an optional callback argument which runs the host app after Sentry initialization.
 - add loadContextsIntegration tests
 - Ref: add missing docs and move sentry web plugin to the inner src folder
 - Ref: Remove deprecated classes (Flutter Plugin for Android) and cleaning up #186

dart/README.md

@@ -40,25 +40,42 @@ import 'dart:async';
 import 'package:sentry/sentry.dart';
 
 Future<void> main() async {
-  await Sentry.init((options) {
-    options.dsn = 'https://[email protected]/add-your-dsn-here';
-  });
-
-  try {
-    aMethodThatMightFail();
-  } catch (exception, stackTrace) {
-    await Sentry.captureException(
-      exception,
-      stackTrace: stackTrace,
-    );
-  }
+  await Sentry.init(
+    (options) {
+      options.dsn = 'https://[email protected]/add-your-dsn-here';
+    }, 
+    initApp, // Init your App.
+  );
 }
 
-void aMethodThatMightFail() {
-  throw null;
+void initApp() {
+  // your app code
 }
 ```
 
+Or, if you want to run your app in your own error zone [runZonedGuarded] :  
+
+```dart
+import 'dart:async';
+import 'package:sentry/sentry.dart';
+
+Future<void> main() async {
+  await Sentry.init(
+    (options) {
+      options.dsn = 'https://[email protected]/add-your-dsn-here';
+    }, 
+  );
+
+  // Init your App.
+  initApp();
+}
+
+void initApp() {
+  // your app code
+}
+
+```
+
 #### Resources
 
 * [![Documentation](https://img.shields.io/badge/documentation-sentry.io-green.svg)](https://docs.sentry.io/platforms/dart/)

dart/example/README.md

@@ -4,9 +4,9 @@ The example in this directory throws an error and sends it to Sentry.io. Use it
 as a source of example code, or to smoke-test your Sentry.io configuration.
 
 To use the example, create a Sentry.io account and get a DSN for your project.
-Then run the following command, replacing "{DSN}" with the one you got from
-Sentry.io:
+In the `main.dart` file, replace the `dsn` value with the one you got from Sentry.io.
+Then run the following command :
 
 ```
-dart example/main.dart {DSN}
+dart example/main.dart
 ```

dart/example/main.dart

@@ -17,9 +17,12 @@ Future<void> main() async {
   SentryEvent processTagEvent(SentryEvent event, Object hint) =>
       event..tags.addAll({'page-locale': 'en-us'});
 
-  await Sentry.init((options) => options
-    ..dsn = dsn
-    ..addEventProcessor(processTagEvent));
+  await Sentry.init(
+    (options) => options
+      ..dsn = dsn
+      ..addEventProcessor(processTagEvent),
+    runApp,
+  );
 
   Sentry.addBreadcrumb(
     Breadcrumb(
@@ -48,7 +51,9 @@ Future<void> main() async {
       ..setTag('build', '579')
       ..setExtra('company-name', 'Dart Inc');
   });
+}
 
+void runApp() async {
   print('\nReporting a complete event example: ');
 
   // Sends a full Sentry event payload to show the different parts of the UI.

dart/example_web/web/main.dart

@@ -11,24 +11,15 @@ const dsn =
     'https://[email protected]/5428562';
 
 Future<void> main() async {
-  querySelector('#output').text = 'Your Dart app is running.';
-
-  querySelector('#btEvent')
-      .onClick
-      .listen((event) => captureCompleteExampleEvent());
-  querySelector('#btMessage').onClick.listen((event) => captureMessage());
-  querySelector('#btException').onClick.listen((event) => captureException());
-
-  await initSentry();
-}
-
-Future<void> initSentry() async {
   SentryEvent processTagEvent(SentryEvent event, Object hint) =>
       event..tags.addAll({'page-locale': 'en-us'});
 
-  await Sentry.init((options) => options
-    ..dsn = dsn
-    ..addEventProcessor(processTagEvent));
+  await Sentry.init(
+    (options) => options
+      ..dsn = dsn
+      ..addEventProcessor(processTagEvent),
+    runApp,
+  );
 
   Sentry.addBreadcrumb(
     Breadcrumb(
@@ -59,6 +50,18 @@ Future<void> initSentry() async {
   });
 }
 
+void runApp() {
+  print('runApp');
+
+  querySelector('#output').text = 'Your Dart app is running.';
+
+  querySelector('#btEvent')
+      .onClick
+      .listen((event) => captureCompleteExampleEvent());
+  querySelector('#btMessage').onClick.listen((event) => captureMessage());
+  querySelector('#btException').onClick.listen((event) => captureException());
+}
+
 void captureMessage() async {
   print('Capturing Message :  ');
   final sentryId = await Sentry.captureMessage(
@@ -81,7 +84,8 @@ void captureException() async {
     print(stackTrace);
     final sentryId = await Sentry.captureException(
       error,
-      stackTrace: stackTrace,
+      stackTrace: stackTrace
+          .toString() /* on safari (14.0) passing a stacktrace object fails */,
     );
 
     print('Capture exception : SentryId: ${sentryId}');

dart/lib/sentry.dart

@@ -3,12 +3,15 @@
 // found in the LICENSE file.
 
 /// A pure Dart client for Sentry.io crash reporting.
+export 'src/default_integrations.dart';
+export 'src/hub.dart';
+export 'src/noop_isolate_error_integration.dart'
+    if (dart.library.io) 'src/isolate_error_integration.dart';
 export 'src/protocol.dart';
 export 'src/scope.dart';
 export 'src/sentry.dart';
 export 'src/sentry_client.dart';
-export 'src/hub.dart';
 export 'src/sentry_options.dart';
-export 'src/transport/transport.dart';
 // useful for integrations
 export 'src/throwable_mechanism.dart';
+export 'src/transport/transport.dart';

dart/lib/src/default_integrations.dart

@@ -0,0 +1,33 @@
+import 'dart:async';
+
+import 'hub.dart';
+import 'protocol.dart';
+import 'sentry.dart';
+import 'sentry_options.dart';
+import 'throwable_mechanism.dart';
+
+/// integration that capture errors on the runZonedGuarded error handler
+Integration runZonedGuardedIntegration(
+  AppRunner appRunner,
+) {
+  void integration(Hub hub, SentryOptions options) {
+    runZonedGuarded(() async {
+      await appRunner();
+    }, (exception, stackTrace) async {
+      // runZonedGuarded doesn't crash the App.
+      const mechanism = Mechanism(type: 'runZonedGuarded', handled: true);
+      final throwableMechanism = ThrowableMechanism(mechanism, exception);
+
+      final event = SentryEvent(
+        throwable: throwableMechanism,
+        level: SentryLevel.fatal,
+      );
+
+      await hub.captureEvent(event, stackTrace: stackTrace);
+    });
+
+    options.sdk.addIntegration('runZonedGuardedIntegration');
+  }
+
+  return integration;
+}

dart/lib/src/isolate_error_integration.dart

@@ -0,0 +1,51 @@
+import 'dart:isolate';
+
+import 'hub.dart';
+import 'protocol.dart';
+import 'sentry_options.dart';
+import 'throwable_mechanism.dart';
+
+/// integration that capture errors on the current Isolate Error handler
+/// which is the main thread.
+void isolateErrorIntegration(Hub hub, SentryOptions options) {
+  final receivePort = _createPort(hub, options);
+
+  Isolate.current.addErrorListener(receivePort.sendPort);
+
+  options.sdk.addIntegration('isolateErrorIntegration');
+}
+
+RawReceivePort _createPort(Hub hub, SentryOptions options) {
+  return RawReceivePort(
+    (dynamic error) async {
+      await handleIsolateError(hub, options, error);
+    },
+  );
+}
+
+/// Parse and raise an event out of the Isolate error.
+/// Visible for testing.
+Future<void> handleIsolateError(
+  Hub hub,
+  SentryOptions options,
+  dynamic error,
+) async {
+  options.logger(SentryLevel.debug, 'Capture from IsolateError $error');
+
+  // https://api.dartlang.org/stable/2.7.0/dart-isolate/Isolate/addErrorListener.html
+  // error is a list of 2 elements
+  if (error is List<dynamic> && error.length == 2) {
+    final dynamic throwable = error.first;
+    final dynamic stackTrace = error.last;
+
+    //  Isolate errors don't crash the App.
+    const mechanism = Mechanism(type: 'isolateError', handled: true);
+    final throwableMechanism = ThrowableMechanism(mechanism, throwable);
+    final event = SentryEvent(
+      throwable: throwableMechanism,
+      level: SentryLevel.fatal,
+    );
+
+    await hub.captureEvent(event, stackTrace: stackTrace);
+  }
+}

dart/lib/src/noop_isolate_error_integration.dart

@@ -0,0 +1,5 @@
+import 'hub.dart';
+import 'sentry_options.dart';
+
+// noop web integration : isolate doesnt' work in browser
+void isolateErrorIntegration(Hub hub, SentryOptions options) {}

dart/lib/src/sentry.dart

@@ -1,15 +1,22 @@
 import 'dart:async';
 
+import 'default_integrations.dart';
 import 'hub.dart';
 import 'hub_adapter.dart';
 import 'noop_hub.dart';
+import 'noop_isolate_error_integration.dart'
+    if (dart.library.io) 'isolate_error_integration.dart';
 import 'protocol.dart';
 import 'sentry_client.dart';
 import 'sentry_options.dart';
+import 'utils.dart';
 
 /// Configuration options callback
 typedef OptionsConfiguration = FutureOr<void> Function(SentryOptions);
 
+/// Runs a callback inside of the `runZonedGuarded` method, useful for running your `runApp(MyApp())`
+typedef AppRunner = FutureOr<void> Function();
+
 /// Sentry SDK main entry point
 class Sentry {
   static Hub _hub = NoOpHub();
@@ -20,11 +27,20 @@ class Sentry {
   static Hub get currentHub => _hub;
 
   /// Initializes the SDK
-  static Future<void> init(OptionsConfiguration optionsConfiguration) async {
+  /// passing a [AppRunner] callback allows to run the app within its own error zone (`runZonedGuarded`)
+  /// https://api.dart.dev/stable/2.10.4/dart-async/runZonedGuarded.html
+  static Future<void> init(
+    OptionsConfiguration optionsConfiguration, [
+    AppRunner appRunner,
+    List<Integration> initialIntegrations,
+  ]) async {
     if (optionsConfiguration == null) {
       throw ArgumentError('OptionsConfiguration is required.');
     }
+
     final options = SentryOptions();
+    await _initDefaultValues(options, appRunner, initialIntegrations);
+
     await optionsConfiguration(options);
 
     if (options == null) {
@@ -34,6 +50,47 @@ class Sentry {
     await _init(options);
   }
 
+  static Future<void> _initDefaultValues(
+    SentryOptions options,
+    AppRunner appRunner,
+    List<Integration> initialIntegrations,
+  ) async {
+    // if no environment is set, we set 'production' by default, but if we know it's
+    // a non-release build, or the SENTRY_ENVIRONMENT is set, we read from it.
+    if (const bool.hasEnvironment('SENTRY_ENVIRONMENT') || !isReleaseMode) {
+      options.environment = const String.fromEnvironment(
+        'SENTRY_ENVIRONMENT',
+        defaultValue: 'debug',
+      );
+    }
+
+    // if the SENTRY_DSN is set, we read from it.
+    options.dsn = const bool.hasEnvironment('SENTRY_DSN')
+        ? const String.fromEnvironment('SENTRY_DSN')
+        : options.dsn;
+
+    // we need to execute integrations in a specific order sometimes,
+    // and this initialIntegrations list makes it possible to inject and add
+    // integrations before the runZonedGuardedIntegration gets added
+    if (initialIntegrations != null && initialIntegrations.isNotEmpty) {
+      initialIntegrations
+          .forEach((integration) => options.addIntegration(integration));
+    }
+
+    // Throws when running on the browser
+    if (!isWeb) {
+      // catch any errors that may occur within the entry function, main()
+      // in the ‘root zone’ where all Dart programs start
+      options.addIntegration(isolateErrorIntegration);
+    }
+
+    // finally the runZonedGuarded, catch any errors in Dart code running
+    // ‘outside’ the Flutter framework
+    if (appRunner != null) {
+      options.addIntegration(runZonedGuardedIntegration(appRunner));
+    }
+  }
+
   /// Initializes the SDK
   static Future<void> _init(SentryOptions options) async {
     if (isEnabled) {

dart/lib/src/sentry_stack_trace_factory.dart

@@ -20,6 +20,7 @@ class SentryStackTraceFactory {
   List<SentryStackFrame> getStackFrames(dynamic stackTrace) {
     if (stackTrace == null) return null;
 
+    // TODO : fix : in release mode on Safari passing a stacktrace object fails, but works if it's passed as String
     final chain = (stackTrace is StackTrace)
         ? Chain.forTrace(stackTrace)
         : (stackTrace is String)

dart/lib/src/utils.dart

@@ -20,3 +20,7 @@ String formatDateAsIso8601WithMillisPrecision(DateTime date) {
 
 /// helper to detect a browser context
 const isWeb = identical(0, 0.0);
+
+/// helper to detect if app is in release mode
+const isReleaseMode =
+    bool.fromEnvironment('dart.vm.product', defaultValue: false);