v9: Parent-child relationship for the PlatformExceptions and Cause

CHANGELOG.md

@@ -13,6 +13,8 @@ Sentry.addFeatureFlag('my-feature', true);
 ### Behavioral changes
 
 - Set log level to `warning` by default when `debug = true` ([#2836](https://github.com/getsentry/sentry-dart/pull/2836))
+- Parent-child relationship for the PlatformExceptions and Cause ([#2803](https://github.com/getsentry/sentry-dart/pull/2803))
+  - Improves and changes exception grouping
 
 ### API Changes
 

dart/lib/src/event_processor/exception/exception_group_event_processor.dart

@@ -0,0 +1,54 @@
+import '../../event_processor.dart';
+import '../../protocol.dart';
+import '../../hint.dart';
+
+/// Group exceptions into a flat list with references to hierarchy.
+class ExceptionGroupEventProcessor implements EventProcessor {
+  @override
+  SentryEvent? apply(SentryEvent event, Hint hint) {
+    final sentryExceptions = event.exceptions ?? [];
+    if (sentryExceptions.isEmpty) {
+      return event;
+    }
+    final firstException = sentryExceptions.first;
+
+    if (sentryExceptions.length > 1 || firstException.exceptions == null) {
+      // If already a list or no child exceptions, no grouping possible/needed.
+      return event;
+    } else {
+      event.exceptions =
+          firstException.flatten().reversed.toList(growable: false);
+      return event;
+    }
+  }
+}
+
+extension _SentryExceptionFlatten on SentryException {
+  List<SentryException> flatten({int? parentId, int id = 0}) {
+    final exceptions = this.exceptions ?? [];
+
+    final newMechanism = mechanism ?? Mechanism(type: "generic");
+    newMechanism
+      ..type = id > 0 ? "chained" : newMechanism.type
+      ..parentId = parentId
+      ..exceptionId = id
+      ..isExceptionGroup = exceptions.isNotEmpty ? true : null;
+
+    mechanism = newMechanism;
+
+    var all = <SentryException>[];
+    all.add(this);
+
+    if (exceptions.isNotEmpty) {
+      final parentId = id;
+      for (var exception in exceptions) {
+        id++;
+        final flattenedExceptions =
+            exception.flatten(parentId: parentId, id: id);
+        id = flattenedExceptions.lastOrNull?.mechanism?.exceptionId ?? id;
+        all.addAll(flattenedExceptions);
+      }
+    }
+    return all.toList(growable: false);
+  }
+}

dart/lib/src/event_processor/exception/io_exception_event_processor.dart

@@ -43,16 +43,27 @@
     SocketException exception,
     SentryEvent event,
   ) {
-    final address = exception.address;
     final osError = exception.osError;
+    SentryException? osException;
+    List<SentryException>? exceptions = event.exceptions;
+    if (osError != null) {
+      // OSError is the underlying error
+      // https://api.dart.dev/stable/dart-io/SocketException/osError.html
+      // https://api.dart.dev/stable/dart-io/OSError-class.html
+      osException = _sentryExceptionFromOsError(osError);
+      final exception = event.exceptions?.firstOrNull;
+      if (exception != null) {
+        exception.addException(osException);
+      } else {
+        exceptions = [osException];
+      }
+    } else {
+      exceptions = event.exceptions;
+    }
+
+    final address = exception.address;
     if (address == null) {
-      event.exceptions = [
-        // OSError is the underlying error
-        // https://api.dart.dev/stable/dart-io/SocketException/osError.html
-        // https://api.dart.dev/stable/dart-io/OSError-class.html
-        if (osError != null) _sentryExceptionfromOsError(osError),
-        ...?event.exceptions,
-      ];
+      event.exceptions = exceptions;
       return event;
     }
     SentryRequest? request;
@@ -71,15 +82,9 @@
       }
     }
 
-    event.request = event.request ?? request;
-    event.exceptions = [
-      // OSError is the underlying error
-      // https://api.dart.dev/stable/dart-io/SocketException/osError.html
-      // https://api.dart.dev/stable/dart-io/OSError-class.html
-      if (osError != null) _sentryExceptionfromOsError(osError),
-      ...?event.exceptions,
-    ];
-    return event;
+    return event
+      ..request = event.request ?? request
+      ..exceptions = exceptions;
   }
 
   // https://api.dart.dev/stable/dart-io/FileSystemException-class.html
@@ -88,18 +93,24 @@
     SentryEvent event,
   ) {
     final osError = exception.osError;
-    event.exceptions = [
+
+    if (osError != null) {
       // OSError is the underlying error
-      // https://api.dart.dev/stable/dart-io/FileSystemException/osError.html
+      // https://api.dart.dev/stable/dart-io/SocketException/osError.html
       // https://api.dart.dev/stable/dart-io/OSError-class.html
-      if (osError != null) _sentryExceptionfromOsError(osError),
-      ...?event.exceptions,
-    ];
+      final osException = _sentryExceptionFromOsError(osError);
+      final exception = event.exceptions?.firstOrNull;
+      if (exception != null) {
+        exception.addException(osException);
+      } else {
+        event.exceptions = [osException];
+      }
+    }
     return event;
   }
 }
 
-SentryException _sentryExceptionfromOsError(OSError osError) {
+SentryException _sentryExceptionFromOsError(OSError osError) {
   return SentryException(
     type: osError.runtimeType.toString(),
     value: osError.toString(),
@@ -110,6 +121,7 @@
       meta: {
         'errno': {'number': osError.errorCode},
       },
+      source: 'osError',
     ),
   );
 }

dart/lib/src/exception_cause.dart

@@ -1,7 +1,8 @@
 /// Holds inner exception and stackTrace combinations contained in other exceptions
 class ExceptionCause {
-  ExceptionCause(this.exception, this.stackTrace);
+  ExceptionCause(this.exception, this.stackTrace, {this.source});
 
   dynamic exception;
   dynamic stackTrace;
+  String? source;
 }

dart/lib/src/protocol/sentry_exception.dart

@@ -26,7 +26,9 @@
   dynamic throwable;
 
   @internal
-  final Map<String, dynamic>? unknown;
+  Map<String, dynamic>? unknown;
+
+  List<SentryException>? _exceptions;
 
   SentryException({
     required this.type,
@@ -86,10 +88,25 @@
         type: type ?? this.type,
         value: value ?? this.value,
         module: module ?? this.module,
-        stackTrace: stackTrace ?? this.stackTrace,
-        mechanism: mechanism ?? this.mechanism,
+        stackTrace: stackTrace ?? this.stackTrace?.copyWith(),
+        mechanism: mechanism ?? this.mechanism?.copyWith(),
         threadId: threadId ?? this.threadId,
         throwable: throwable ?? this.throwable,
         unknown: unknown,
       );
+
+  @internal
+  List<SentryException>? get exceptions =>
+      _exceptions != null ? List.unmodifiable(_exceptions!) : null;
+
+  @internal
+  set exceptions(List<SentryException>? value) {
+    _exceptions = value;
+  }
+
+  @internal
+  void addException(SentryException exception) {
+    _exceptions ??= [];
+    _exceptions!.add(exception);
+  }
 }

dart/lib/src/recursive_exception_cause_extractor.dart

@@ -16,8 +16,10 @@ class RecursiveExceptionCauseExtractor {
     final circularityDetector = <dynamic>{};
 
     var currentException = exception;
-    ExceptionCause? currentExceptionCause =
-        ExceptionCause(exception, stackTrace);
+    ExceptionCause? currentExceptionCause = ExceptionCause(
+      exception,
+      stackTrace,
+    );
 
     while (currentException != null &&
         currentExceptionCause != null &&

dart/lib/src/sentry.dart

@@ -7,6 +7,7 @@ import 'environment/environment_variables.dart';
 import 'event_processor/deduplication_event_processor.dart';
 import 'event_processor/enricher/enricher_event_processor.dart';
 import 'event_processor/exception/exception_event_processor.dart';
+import 'event_processor/exception/exception_group_event_processor.dart';
 import 'hint.dart';
 import 'hub.dart';
 import 'hub_adapter.dart';
@@ -113,6 +114,9 @@ class Sentry {
     options.addEventProcessor(DeduplicationEventProcessor(options));
 
     options.prependExceptionTypeIdentifier(DartExceptionTypeIdentifier());
+
+    // Added last to ensure all error events have correct parent/child relationships
+    options.addEventProcessor(ExceptionGroupEventProcessor());
   }
 
   /// This method reads available environment variables and uses them

dart/lib/src/sentry_client.dart

@@ -211,12 +211,13 @@ class SentryClient {
 
   SentryEvent _prepareEvent(SentryEvent event, Hint hint,
       {dynamic stackTrace}) {
-    event.serverName = event.serverName ?? _options.serverName;
-    event.dist = event.dist ?? _options.dist;
-    event.environment = event.environment ?? _options.environment;
-    event.release = event.release ?? _options.release;
-    event.sdk = event.sdk ?? _options.sdk;
-    event.platform = event.platform ?? sdkPlatform(_options.platform.isWeb);
+    event
+      ..serverName = event.serverName ?? _options.serverName
+      ..dist = event.dist ?? _options.dist
+      ..environment = event.environment ?? _options.environment
+      ..release = event.release ?? _options.release
+      ..sdk = event.sdk ?? _options.sdk
+      ..platform = event.platform ?? sdkPlatform(_options.platform.isWeb);
 
     if (event is SentryTransaction) {
       return event;
@@ -235,18 +236,26 @@ class SentryClient {
     final isolateId = isolateName?.hashCode;
 
     if (event.throwableMechanism != null) {
-      final extractedExceptions = _exceptionFactory.extractor
+      final extractedExceptionCauses = _exceptionFactory.extractor
           .flatten(event.throwableMechanism, stackTrace);
 
-      final sentryExceptions = <SentryException>[];
+      SentryException? rootException;
+      SentryException? currentException;
       final sentryThreads = <SentryThread>[];
 
-      for (final extractedException in extractedExceptions) {
+      for (final extractedExceptionCause in extractedExceptionCauses) {
         var sentryException = _exceptionFactory.getSentryException(
-          extractedException.exception,
-          stackTrace: extractedException.stackTrace,
+          extractedExceptionCause.exception,
+          stackTrace: extractedExceptionCause.stackTrace,
           removeSentryFrames: hint.get(TypeCheckHint.currentStackTrace),
         );
+        if (extractedExceptionCause.source != null) {
+          var mechanism =
+              sentryException.mechanism ?? Mechanism(type: "generic");
+
+          mechanism.source = extractedExceptionCause.source;
+          sentryException.mechanism = mechanism;
+        }
 
         SentryThread? sentryThread;
 
@@ -262,21 +271,25 @@ class SentryClient {
           );
         }
 
-        sentryExceptions.add(sentryException);
+        rootException ??= sentryException;
+        currentException?.addException(sentryException);
+        currentException = sentryException;
+
         if (sentryThread != null) {
           sentryThreads.add(sentryThread);
         }
       }
 
-      event.exceptions = [
-        ...?event.exceptions,
-        ...sentryExceptions,
-      ];
-      event.threads = [
-        ...?event.threads,
-        ...sentryThreads,
-      ];
-      return event;
+      final exceptions = [...?event.exceptions];
+      if (rootException != null) {
+        exceptions.add(rootException);
+      }
+      return event
+        ..exceptions = exceptions
+        ..threads = [
+          ...?event.threads,
+          ...sentryThreads,
+        ];
     }
 
     // The stacktrace is not part of an exception,