feat: Add exception recording. (#250)

Adds basic exception recording and updates example app.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds `Observe.recordException` and updates the example app to report
Flutter and zone errors; includes a button to trigger an error.
> 
> - **SDK / Observability**:
> - **New API**: `Observe.recordException(exception, {stackTrace,
attributes})` records exceptions by creating an error span
`launchdarkly.error` and attaching optional metadata.
> - **Example App (`example/lib/main.dart`)**:
> - Reports Flutter framework errors via `FlutterError.onError` using
`Observe.recordException`.
> - Reports errors from `runZonedGuarded` handler via
`Observe.recordException`.
> - Adds a button to intentionally throw an exception to test unhandled
error reporting.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
cde38af. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

sdk/@launchdarkly/launchdarkly_flutter_observability/example/lib/main.dart

@@ -34,10 +34,18 @@ void main() {
 
       LDSingleton.client!.start();
 
+      // Report any errors handled by flutter.
+      FlutterError.onError = (FlutterErrorDetails details) {
+        Observe.recordException(details.exception, stackTrace: details.stack);
+      };
+
       runApp(MyApp());
     },
     (err, stack) {
-      // TODO: Record errors.
+      // Report any errors reported from the guarded zone.
+      Observe.recordException(err, stackTrace: stack);
+
+      // Any additional default error handling.
     },
   );
 }
@@ -148,6 +156,12 @@ class _MyHomePageState extends State<MyHomePage> {
           // wireframe for each widget.
           mainAxisAlignment: MainAxisAlignment.center,
           children: <Widget>[
+            ElevatedButton(
+              onPressed: () {
+                throw Exception('This is an error!');
+              },
+              child: const Text('Trigger unhandled error'),
+            ),
             const Text('You have pushed the button this many times:'),
             Text(
               '$_counter',

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/observe.dart

@@ -5,6 +5,7 @@ import 'api/span_kind.dart';
 import 'otel/conversions.dart';
 
 const _launchDarklyTracerName = 'launchdarkly-observability';
+const _launchDarklyErrorSpanName = 'launchdarkly.error';
 
 /// Singleton used to access observability features.
 final class Observe {
@@ -26,4 +27,38 @@ final class Observe {
 
     return wrapSpan(span, token);
   }
+
+  /// Record an exception with an optional stack trace and attributes.
+  ///
+  /// In dart the stack trace is independent of the exception object and can
+  /// be caught at the same time as an exception.
+  /// ```dart
+  /// try {
+  ///   // thing that throws
+  /// catch(err, stack) {
+  ///   Observe.record(err, stacktrace: stack);
+  /// }
+  /// ```
+  ///
+  /// In order to capture a stack trace that isn't at the origin of the catch
+  /// the `StackTrace.current` method can be used.
+  ///
+  /// The value of the [exception] object will be incorporated into traces
+  /// using its `toString` method.
+  static void recordException(
+    dynamic exception, {
+    StackTrace? stackTrace,
+    Map<String, Attribute>? attributes,
+  }) {
+    // The OTEL library currently doesn't have a way to differentiate if there
+    // is an active span or not. So currently we always create a span for
+    // exceptions.
+    final span = startSpan(_launchDarklyErrorSpanName);
+    span.recordException(
+      exception,
+      attributes: attributes,
+      stackTrace: stackTrace ?? StackTrace.empty,
+    );
+    span.end();
+  }
 }