feat: autocapture unhandled exceptions

CHANGELOG.md

@@ -1,5 +1,11 @@
 ## Next
 
+- feat: add autocapture exceptions ([#214](https://github.com/PostHog/posthog-flutter/pull/214))
+  - **Note**: The following features are not yet supported:
+    - Flutter web platform (PlatformDispatcher.onError not implemented)
+    - Instrumentation to enable background isolate error auto capture
+    - Native iOS exception capture
+
 ## 5.8.0
 
 - feat: surveys GA ([#215](https://github.com/PostHog/posthog-flutter/pull/215))

android/src/main/kotlin/com/posthog/flutter/PosthogFlutterPlugin.kt

@@ -293,6 +293,16 @@ class PosthogFlutterPlugin :
                     }
                 }
 
+                // Configure error tracking autocapture
+                posthogConfig.getIfNotNull<Map<String, Any>>("errorTrackingConfig") { errorConfig ->
+                    errorConfig.getIfNotNull<Boolean>("captureNativeExceptions") {
+                        errorTrackingConfig.autoCapture = it
+                    }
+                    errorConfig.getIfNotNull<List<String>>("inAppIncludes") { includes ->
+                        errorTrackingConfig.inAppIncludes.addAll(includes)
+                    }
+                }
+
                 sdkName = "posthog-flutter"
                 sdkVersion = postHogVersion
             }

example/lib/main.dart

@@ -16,6 +16,13 @@ Future<void> main() async {
   config.sessionReplayConfig.maskAllImages = false;
   config.sessionReplayConfig.throttleDelay = const Duration(milliseconds: 1000);
   config.flushAt = 1;
+
+  // Configure error tracking and exception capture
+  config.errorTrackingConfig.captureFlutterErrors =
+      true; // Capture Flutter framework errors
+  config.errorTrackingConfig.capturePlatformDispatcherErrors =
+      true; // Capture Dart runtime errors
+
   await Posthog().setup(config);
 
   runApp(const MyApp());

lib/src/error_tracking/dart_exception_processor.dart

@@ -1,5 +1,6 @@
 import 'package:stack_trace/stack_trace.dart';
 import 'utils/isolate_utils.dart' as isolate_utils;
+import 'posthog_exception.dart';
 
 class DartExceptionProcessor {
   /// Converts Dart error/exception and stack trace to PostHog exception format
@@ -12,12 +13,23 @@ class DartExceptionProcessor {
     bool inAppByDefault = true,
     StackTrace Function()? stackTraceProvider, //for testing
   }) {
+    // Extract PostHog metadata if error is wrapped in PostHogException
+    String mechanismType = 'generic';
+    bool handled = true;
+    Object currentError = error;
+
+    if (error is PostHogException) {
+      handled = error.handled;
+      mechanismType = error.mechanism;
+      currentError = error.source;
+    }
+
     StackTrace? effectiveStackTrace = stackTrace;
     bool isGeneratedStackTrace = false;
 
     // If it's an Error, try to use its built-in stackTrace
-    if (error is Error) {
-      effectiveStackTrace ??= error.stackTrace;
+    if (currentError is Error) {
+      effectiveStackTrace ??= currentError.stackTrace;
     }
 
     // If still null or empty, get current stack trace
@@ -41,7 +53,7 @@ class DartExceptionProcessor {
           )
         : <Map<String, dynamic>>[];
 
-    final errorType = _getExceptionType(error);
+    final errorType = _getExceptionType(currentError);
 
     // Mark exception as synthetic if:
     // - runtimeType.toString() returned empty/null (fallback to 'Error' type)
@@ -53,14 +65,14 @@ class DartExceptionProcessor {
     final exceptionData = <String, dynamic>{
       'type': errorType ?? 'Error',
       'mechanism': {
-        'handled': true, // always true for now
+        'handled': handled,
         'synthetic': isSynthetic,
-        'type': 'generic',
+        'type': mechanismType,
       }
     };
 
     // Add exception message, if available
-    final errorMessage = error.toString();
+    final errorMessage = currentError.toString();
     if (errorMessage.isNotEmpty) {
       exceptionData['value'] = errorMessage;
     }

lib/src/error_tracking/isolate_handler_io.dart

@@ -0,0 +1,33 @@
+import 'dart:isolate';
+
+import 'package:posthog_flutter/src/util/logging.dart';
+
+/// Native platform implementation of isolate error handling
+class IsolateErrorHandler {
+  RawReceivePort? _isolateErrorPort;
+
+  /// Add error listener to current isolate (should be main isolate)
+  void addErrorListener(Function(dynamic) onError) {
+    // In Flutter, the main isolate typically has debugName 'main'
+    final isolateName = Isolate.current.debugName;
+    if (isolateName != null && isolateName != 'main') {
+      printIfDebug(
+          'PostHog isolate error handler is being set up in isolate "$isolateName" instead of main isolate');
+    }
+
+    _isolateErrorPort = RawReceivePort(onError);
+    Isolate.current.addErrorListener(_isolateErrorPort!.sendPort);
+  }
+
+  /// Remove error listener and clean up
+  void removeErrorListener() {
+    if (_isolateErrorPort != null) {
+      _isolateErrorPort!.close();
+      Isolate.current.removeErrorListener(_isolateErrorPort!.sendPort);
+      _isolateErrorPort = null;
+    }
+  }
+
+  /// Check if error listener is active
+  bool get isActive => _isolateErrorPort != null;
+}

lib/src/error_tracking/isolate_handler_web.dart

@@ -0,0 +1,16 @@
+/// Web platform stub implementation of isolate error handling
+/// Isolates are not available on web, so this is a no-op implementation
+class IsolateErrorHandler {
+  /// Add error listener to current isolate (no-op on web)
+  void addErrorListener(Function(dynamic) onError) {
+    // No-op: Isolates are not available on web
+  }
+
+  /// Remove error listener and clean up (no-op on web)
+  void removeErrorListener() {
+    // No-op: Isolates are not available on web
+  }
+
+  /// Check if error listener is active (always false on web)
+  bool get isActive => false;
+}

lib/src/error_tracking/posthog_error_tracking_autocapture_integration.dart

@@ -0,0 +1,234 @@
+import 'dart:ui';
+
+import 'package:flutter/foundation.dart';
+import 'package:posthog_flutter/src/util/platform_io_stub.dart';
+
+import 'isolate_handler_io.dart'
+    if (dart.library.html) 'isolate_handler_web.dart';
+import 'package:posthog_flutter/src/util/logging.dart';
+
+import '../posthog_flutter_platform_interface.dart';
+import '../posthog_config.dart';
+import 'posthog_exception.dart';
+
+/// Handles automatic capture of Flutter and Dart exceptions
+class PostHogErrorTrackingAutoCaptureIntegration {
+  final PostHogErrorTrackingConfig _config;
+  final PosthogFlutterPlatformInterface _posthog;
+
+  // Store original handlers (we'll chain with them from our handler)
+  FlutterExceptionHandler? _originalFlutterErrorHandler;
+  ErrorCallback? _originalPlatformErrorHandler;
+
+  // Isolate error handling
+  final IsolateErrorHandler _isolateErrorHandler = IsolateErrorHandler();
+
+  bool _isEnabled = false;
+
+  static PostHogErrorTrackingAutoCaptureIntegration? _instance;
+
+  PostHogErrorTrackingAutoCaptureIntegration._({
+    required PostHogErrorTrackingConfig config,
+    required PosthogFlutterPlatformInterface posthog,
+  })  : _config = config,
+        _posthog = posthog;
+
+  /// Install the autocapture integration (can only be installed once)
+  static PostHogErrorTrackingAutoCaptureIntegration? install({
+    required PostHogErrorTrackingConfig config,
+    required PosthogFlutterPlatformInterface posthog,
+  }) {
+    if (_instance != null) {
+      debugPrint(
+          'PostHog: Error tracking autocapture integration is already installed. Call PostHogErrorTrackingAutoCaptureIntegration.uninstall() first.');
+      return null;
+    }
+
+    final instance = PostHogErrorTrackingAutoCaptureIntegration._(
+      config: config,
+      posthog: posthog,
+    );
+
+    _instance = instance;
+
+    if (config.captureFlutterErrors ||
+        config.capturePlatformDispatcherErrors ||
+        config.captureIsolateErrors) {
+      instance.start();
+    }
+
+    return instance;
+  }
+
+  /// Uninstall the autocapture integration
+  static void uninstall() {
+    if (_instance != null) {
+      _instance!.stop();
+      _instance = null;
+    }
+  }
+
+  /// Start automatic exception capture
+  void start() {
+    if (_isEnabled) return;
+
+    _isEnabled = true;
+
+    // Set up Flutter error handler if enabled
+    if (_config.captureFlutterErrors) {
+      _setupFlutterErrorHandler();
+    }
+
+    // Set up platform error handler if enabled
+    if (_config.capturePlatformDispatcherErrors) {
+      _setupPlatformErrorHandler();
+    }
+
+    // Set up isolate error handler if enabled
+    if (_config.captureIsolateErrors) {
+      _setupIsolateErrorHandler();
+    }
+  }
+
+  /// Stop automatic exception capture (restores original handlers)
+  void stop() {
+    if (!_isEnabled) return;
+
+    _isEnabled = false;
+
+    // Restore original handlers only if our own handler is still set
+    if (FlutterError.onError == _posthogFlutterErrorHandler) {
+      FlutterError.onError = _originalFlutterErrorHandler;
+    }
+    if (PlatformDispatcher.instance.onError == _posthogPlatformErrorHandler) {
+      PlatformDispatcher.instance.onError = _originalPlatformErrorHandler;
+    }
+
+    // Clean up isolate error handler
+    _isolateErrorHandler.removeErrorListener();
+
+    // release refs
+    _originalFlutterErrorHandler = null;
+    _originalPlatformErrorHandler = null;
+  }
+
+  /// Flutter framework error handler
+  void _setupFlutterErrorHandler() {
+    // prevent circular calls
+    if (FlutterError.onError == _posthogFlutterErrorHandler) {
+      return;
+    }
+
+    _originalFlutterErrorHandler = FlutterError.onError;
+
+    FlutterError.onError = _posthogFlutterErrorHandler;
+  }
+
+  void _posthogFlutterErrorHandler(FlutterErrorDetails details) {
+    if (!details.silent || _config.captureSilentFlutterErrors) {
+      // Collect additional context information
+      //(see: https://github.com/getsentry/sentry-dart/blob/a69a51fd1695dd93024be80a50ad05dd990b2b82/packages/flutter/lib/src/integrations/flutter_error_integration.dart#L35-L60)
+      final context = details.context?.toDescription();
+      final collector = details.informationCollector?.call() ?? [];
+      final information = collector.isNotEmpty
+          ? (StringBuffer()..writeAll(collector, '\n')).toString()
+          : null;
+      final library = details.library;
+      final errorSummary = details.toStringShort();
+
+      // Build additional properties with Flutter-specific details
+      final flutterErrorDetails = <String, Object>{
+        if (context != null) 'context': 'thrown $context',
+        if (information != null) 'information': information,
+        if (library != null) 'library': library,
+        'error_summary': errorSummary,
+        'silent': details.silent,
+      };
+
+      final wrappedError = PostHogException(
+          source: details.exception, mechanism: 'FlutterError', handled: false);
+
+      _captureException(
+        error: wrappedError,
+        stackTrace: details.stack,
+        properties: {'flutter_error_details': flutterErrorDetails},
+      );
+    } else {
+      printIfDebug(
+          "Error not captured because FlutterErrorDetails.silent is true and captureSilentFlutterErrors is false");
+    }
+
+    // Call the original handler, if any
+    _originalFlutterErrorHandler?.call(details);
+  }
+
+  /// Platform error handler for Dart runtime errors
+  void _setupPlatformErrorHandler() {
+    // On web, PlatformDispatcher.onError is not implemented. Skip for now
+    // See: https://github.com/flutter/flutter/issues/100277
+    if (!isSupportedPlatform()) {
+      return;
+    }
+
+    // prevent circular calls
+    if (PlatformDispatcher.instance.onError == _posthogPlatformErrorHandler) {
+      return;
+    }
+
+    _originalPlatformErrorHandler = PlatformDispatcher.instance.onError;
+    PlatformDispatcher.instance.onError = _posthogPlatformErrorHandler;
+  }
+
+  bool _posthogPlatformErrorHandler(Object error, StackTrace stackTrace) {
+    final wrappedError = PostHogException(
+      source: error,
+      mechanism: 'PlatformDispatcher',
+      handled: false,
+    );
+
+    _captureException(error: wrappedError, stackTrace: stackTrace);
+
+    // Call the original handler, if any
+    // False otherwise, so that default fallback mechanism is used
+    return _originalPlatformErrorHandler?.call(error, stackTrace) ?? false;
+  }
+
+  /// Isolate error handler for current isolate errors
+  void _setupIsolateErrorHandler() {
+    if (!_config.captureIsolateErrors) {
+      return;
+    }
+
+    _isolateErrorHandler.addErrorListener(_posthogIsolateErrorHandler);
+  }
+
+  void _posthogIsolateErrorHandler(dynamic error) {
+    // Isolate errors come as List<dynamic> with [errorString, stackTraceString]
+    // See: https://api.dartlang.org/stable/2.7.0/dart-isolate/Isolate/addErrorListener.html
+    if (error is List && error.length == 2) {
+      final String errorString = error.first;
+      final String? stackTraceString = error.last;
+
+      final wrappedError = PostHogException(
+        source: errorString,
+        mechanism: 'isolateError',
+        handled: false,
+      );
+
+      final stackTrace = stackTraceString != null
+          ? StackTrace.fromString(stackTraceString)
+          : null;
+
+      _captureException(error: wrappedError, stackTrace: stackTrace);
+    }
+  }
+
+  Future<void> _captureException({
+    required PostHogException error,
+    required StackTrace? stackTrace,
+    Map<String, Object>? properties,
+  }) {
+    return _posthog.captureException(
+        error: error, stackTrace: stackTrace, properties: properties);
+  }
+}