v9: Parent-child relationship for the PlatformExceptions and Cause

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+### Behavioral changes
+
+- Parent-child relationship for the PlatformExceptions and Cause ([#2803](https://github.com/getsentry/sentry-dart/pull/2803))
+  - Improves and changes exception grouping
+
 ## 9.0.0-alpha.2
 
 ### Features

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

@@ -0,0 +1,23 @@
+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 {
+      final grouped = firstException.flatten().reversed.toList(growable: false);
+      return event.copyWith(exceptions: grouped);
+    }
+  }
+}

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

@@ -45,17 +45,24 @@
     SocketException exception,
     SentryEvent event,
   ) {
-    final address = exception.address;
     final osError = exception.osError;
+    SentryException? osException;
+    List<SentryException>? 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);
+      osException.exceptions = event.exceptions;
+      exceptions = [osException];
+    } else {
+      exceptions = event.exceptions;
+    }
+
+    final address = exception.address;
     if (address == null) {
       return event.copyWith(
-        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,
-        ],
+        exceptions: exceptions,
       );
     }
     SentryRequest? request;
@@ -76,13 +83,7 @@
 
     return event.copyWith(
       request: event.request ?? request,
-      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,
-      ],
+      exceptions: exceptions,
     );
   }
 
@@ -92,19 +93,27 @@
     SentryEvent event,
   ) {
     final osError = exception.osError;
+
+    SentryException? osException;
+    List<SentryException>? 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);
+      osException.exceptions = event.exceptions;
+      exceptions = [osException];
+    } else {
+      exceptions = event.exceptions;
+    }
+
     return event.copyWith(
-      exceptions: [
-        // OSError is the underlying error
-        // https://api.dart.dev/stable/dart-io/FileSystemException/osError.html
-        // https://api.dart.dev/stable/dart-io/OSError-class.html
-        if (osError != null) _sentryExceptionfromOsError(osError),
-        ...?event.exceptions,
-      ],
+      exceptions: exceptions,
     );
   }
 }
 
-SentryException _sentryExceptionfromOsError(OSError osError) {
+SentryException _sentryExceptionFromOsError(OSError osError) {
   return SentryException(
     type: osError.runtimeType.toString(),
     value: osError.toString(),
@@ -115,6 +124,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

@@ -4,7 +4,6 @@ import '../protocol.dart';
 import 'access_aware_map.dart';
 
 /// The Exception Interface specifies an exception or error that occurred in a program.
-@immutable
 class SentryException {
   /// Required. The type of exception
   final String? type;
@@ -29,7 +28,9 @@ class SentryException {
   @internal
   final Map<String, dynamic>? unknown;
 
-  const SentryException({
+  List<SentryException>? _exceptions;
+
+  SentryException({
     required this.type,
     required this.value,
     this.module,
@@ -92,4 +93,51 @@ class SentryException {
         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);
+  }
+
+  @internal
+  List<SentryException> flatten({int? parentId, int id = 0}) {
+    final exceptions = this.exceptions ?? [];
+
+    var mechanism = this.mechanism ?? Mechanism(type: "generic");
+    mechanism = mechanism.copyWith(
+      type: id > 0 ? "chained" : null,
+      parentId: parentId,
+      exceptionId: id,
+      isExceptionGroup: exceptions.length > 1 ? true : null,
+    );
+
+    final exception = copyWith(
+      mechanism: mechanism,
+    );
+
+    var all = <SentryException>[];
+    all.add(exception);
+
+    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/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';
@@ -110,6 +111,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

@@ -237,18 +237,27 @@ 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 = mechanism.copyWith(
+            source: extractedExceptionCause.source,
+          );
+          sentryException = sentryException.copyWith(mechanism: mechanism);
+        }
 
         SentryThread? sentryThread;
 
@@ -264,14 +273,21 @@ class SentryClient {
           );
         }
 
-        sentryExceptions.add(sentryException);
+        rootException ??= sentryException;
+        currentException?.addException(sentryException);
+        currentException = sentryException;
+
         if (sentryThread != null) {
           sentryThreads.add(sentryThread);
         }
       }
 
+      final exceptions = [...?event.exceptions];
+      if (rootException != null) {
+        exceptions.add(rootException);
+      }
       return event.copyWith(
-        exceptions: [...?event.exceptions, ...sentryExceptions],
+        exceptions: exceptions,
         threads: [
           ...?event.threads,
           ...sentryThreads,

dart/lib/src/sentry_exception_factory.dart

@@ -22,6 +22,7 @@ class SentryExceptionFactory {
   }) {
     var throwable = exception;
     Mechanism? mechanism;
+
     bool? snapshot;
     if (exception is ThrowableMechanism) {
       throwable = exception.throwable;