Feat/dart default integrations

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,10 +40,48 @@ 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';
-  });
+  await Sentry.init(
+    (options) {
+      options.dsn = 'https://[email protected]/add-your-dsn-here';
+    }, 
+    initApp, // Init your App.
+  );
+}
+
+void initApp() {
+  try {
+    aMethodThatMightFail();
+  } catch (exception, stackTrace) {
+    await Sentry.captureException(
+      exception,
+      stackTrace: stackTrace,
+    );
+  }
+}
+
+void aMethodThatMightFail() {
+  throw null;
+}
+```
+
+Or, if you don't want to run your app in its 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() {
   try {
     aMethodThatMightFail();
   } catch (exception, stackTrace) {

dart/example/main.dart

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import 'dart:async';
+import 'dart:io';
 
 import 'package:sentry/sentry.dart';
 
@@ -17,9 +18,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 +52,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.
@@ -82,6 +88,8 @@ Future<void> main() async {
   } finally {
     await Sentry.close();
   }
+
+  exit(0);
 }
 
 Future<void> loadConfig() async {

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(

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);
 
+// run main app callback
+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,44 @@ 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;
+
+    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/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);