feat: Add basic lifecycle instrumentation. (#245)

## Summary

Adds basic support for lifecycle instrumentation.

The code inside the `instrumentation/lifecycle/platform` folder is a
port of the code in the LD flutter SDK. Potentially we could move that
to a shared library. We split the LD SDK into layers, but there wasn't
any need for a flutter specific platform layer sans SDK. (It is dart
only, then client-side dart, and then flutter. But no flutter platform
library.)

## How did you test this change?

Manual testing.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Introduce lifecycle instrumentation that emits spans on Flutter app
state changes across IO and Web platforms, and wire it into the
observability plugin.
> 
> - **Observability**:
>   - **Lifecycle instrumentation**:
> - Add `Instrumentation` interface and `LifecycleInstrumentation` that
listens to `AppLifecycleState` and emits spans via `Observe` with
attributes from `LifecycleConventions`.
> - Define `LifecycleConventions` with span name `device.app.lifecycle`
and attribute `flutter.app.state` mapped from `AppLifecycleState`.
> - Implement platform listeners `platform/io_lifecycle_listener.dart`
(uses `AppLifecycleListener`) and `platform/js_lifecycle_listener.dart`
(uses document visibility); include a stub fallback.
>   - **Plugin integration**:
> - Update `ObservabilityPlugin` to instantiate and hold
`LifecycleInstrumentation` on construction.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
d150c19. 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/lib/src/instrumentation/instrumentation.dart

@@ -0,0 +1,2 @@
+/// Interfaces which instrumentations should implement.
+interface class Instrumentation {}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/instrumentation/lifecycle/lifecycle_conventions.dart

@@ -0,0 +1,54 @@
+import 'dart:ui';
+import '../../api/attribute.dart';
+
+const _lifecycleSpanName = "device.app.lifecycle";
+const _flutterAppState = "flutter.app.state";
+
+enum LifecycleState {
+  detached('detached'),
+  resumed('resumed'),
+  inactive('inactive'),
+  hidden('hidden'),
+  paused('paused');
+
+  final String stringValue;
+
+  const LifecycleState(String value) : stringValue = value;
+
+  @override
+  String toString() {
+    return stringValue;
+  }
+
+  static LifecycleState fromAppLifecycleState(AppLifecycleState state) {
+    switch (state) {
+      case AppLifecycleState.detached:
+        return LifecycleState.detached;
+      case AppLifecycleState.resumed:
+        return LifecycleState.resumed;
+      case AppLifecycleState.inactive:
+        return LifecycleState.inactive;
+      case AppLifecycleState.hidden:
+        return LifecycleState.hidden;
+      case AppLifecycleState.paused:
+        return LifecycleState.paused;
+    }
+  }
+}
+
+/// LaunchDarkly specific lifecycle convention inspired by the otel mobile
+/// events semantic convention.
+final class LifecycleConventions {
+  static Map<String, Attribute> getAttributes({
+    required AppLifecycleState state,
+  }) {
+    return {
+      _flutterAppState: StringAttribute(
+        LifecycleState.fromAppLifecycleState(state).toString(),
+      ),
+    };
+  }
+
+  /// The name to use for the span.
+  static const spanName = _lifecycleSpanName;
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/instrumentation/lifecycle/lifecycle_instrumentation.dart

@@ -0,0 +1,57 @@
+import 'package:flutter/scheduler.dart';
+import 'package:launchdarkly_flutter_observability/launchdarkly_flutter_observability.dart';
+import 'package:launchdarkly_flutter_observability/src/instrumentation/instrumentation.dart';
+import 'package:launchdarkly_flutter_observability/src/instrumentation/lifecycle/lifecycle_conventions.dart';
+
+import '../../observe.dart';
+import 'platform/stub_lifecycle_listener.dart'
+    if (dart.library.io) 'platform/io_lifecycle_listener.dart'
+    if (dart.library.js_interop) 'platform/js_lifecycle_listener.dart';
+
+final class LifecycleInstrumentation implements Instrumentation {
+  late final LDAppLifecycleListener _lifecycleListener;
+
+  LifecycleInstrumentation() {
+    final initialState = SchedulerBinding.instance.lifecycleState;
+    if (initialState != null) {
+      _handleApplicationLifecycle(initialState);
+    }
+
+    _lifecycleListener = LDAppLifecycleListener();
+    _lifecycleListener.stream.listen(_handleApplicationLifecycle);
+  }
+
+  /// The application lifecycle is as follows.
+  /// Diagram based on: https://api.flutter.dev/flutter/widgets/AppLifecycleListener-class.html
+  /// +-----------+       onStart             +-----------+
+  /// |           +--------------------------->           |
+  /// | Detached  |                           | Resumed   |
+  /// |           |                           |           |
+  /// +--------^--+                           +-^-------+-+
+  ///          |                                |       |
+  ///          |onDetach              onInactive|       |onResume
+  ///          |                                |       |
+  ///          |  onPause                       |       |
+  /// +--------+--+       +-----------+onHide +-+-------v-+
+  /// |           <-------+           <-------+           |
+  /// | Paused    |       | Hidden    |       | Inactive  |
+  /// |           +------->           +------->           |
+  /// +-----------+       +-----------+onShow +-----------+
+  ///             onRestart
+  ///
+  /// On iOS/Android the hidden state is synthesized in the process of pausing,
+  /// so it will always hide before being paused. On desktop/web platforms
+  /// hidden may happen when the app is covered.
+  void _handleApplicationLifecycle(AppLifecycleState state) {
+    Observe.startSpan(
+        LifecycleConventions.spanName,
+        attributes: LifecycleConventions.getAttributes(state: state),
+      )
+      ..setStatus(SpanStatusCode.ok)
+      ..end();
+  }
+
+  void dispose() {
+    _lifecycleListener.close();
+  }
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/instrumentation/lifecycle/platform/io_lifecycle_listener.dart

@@ -0,0 +1,31 @@
+import 'dart:async';
+
+import 'package:flutter/widgets.dart';
+
+/// Lifecycle listener that uses the Flutter [AppLifecycleListener].
+/// Unfortunately, the [AppLifecycleListener] does not support web very well at
+/// the moment, so the [LDAppLifecycleListener] was created.
+class LDAppLifecycleListener {
+  late final StreamController<AppLifecycleState> _streamController;
+  AppLifecycleListener? _underlyingListener;
+
+  LDAppLifecycleListener() {
+    _streamController = StreamController.broadcast(
+      onListen: () {
+        _underlyingListener = AppLifecycleListener(
+          onStateChange: (state) => _streamController.add(state),
+        );
+      },
+      onCancel: () {
+        _underlyingListener?.dispose();
+        _underlyingListener = null;
+      },
+    );
+  }
+
+  Stream<AppLifecycleState> get stream => _streamController.stream;
+
+  void close() {
+    _streamController.close();
+  }
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/instrumentation/lifecycle/platform/js_lifecycle_listener.dart

@@ -0,0 +1,38 @@
+import 'dart:async';
+import 'dart:js_interop';
+import 'package:web/web.dart' as web;
+
+import 'package:flutter/widgets.dart';
+
+/// Lifecycle listener that uses the underlying visibility of the html web
+/// document to emit events.
+class LDAppLifecycleListener {
+  late final StreamController<AppLifecycleState> _streamController;
+
+  LDAppLifecycleListener() {
+    _streamController = StreamController.broadcast();
+
+    void listenerFunc(web.Event event) => _streamController.add(
+      web.document.hidden == true
+          ? AppLifecycleState.hidden
+          : AppLifecycleState.resumed,
+    );
+
+    /// Use a stable reference for the JS listener.
+    final listenerJS = listenerFunc.toJS;
+
+    _streamController.onListen = () {
+      web.document.addEventListener('visibilitychange', listenerJS);
+    };
+
+    _streamController.onCancel = () {
+      web.document.removeEventListener('visibilitychange', listenerJS);
+    };
+  }
+
+  Stream<AppLifecycleState> get stream => _streamController.stream;
+
+  void close() {
+    _streamController.close();
+  }
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/instrumentation/lifecycle/platform/stub_lifecycle_listener.dart

@@ -0,0 +1,10 @@
+import 'package:flutter/widgets.dart';
+
+class LDAppLifecycleListener {
+  Stream<AppLifecycleState> get stream =>
+      throw Exception('Stub implementation');
+
+  void close() {
+    throw Exception('Stub implementation');
+  }
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/plugin/observability_plugin.dart

@@ -2,6 +2,8 @@ import 'dart:collection';
 
 import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
 import 'package:launchdarkly_flutter_observability/src/api/span_status_code.dart';
+import 'package:launchdarkly_flutter_observability/src/instrumentation/instrumentation.dart';
+import 'package:launchdarkly_flutter_observability/src/instrumentation/lifecycle/lifecycle_instrumentation.dart';
 import 'package:launchdarkly_flutter_observability/src/otel/feature_flag_convention.dart';
 import 'package:launchdarkly_flutter_observability/src/otel/setup.dart';
 
@@ -66,10 +68,15 @@ final class _ObservabilityHook extends Hook {
 
 /// LaunchDarkly Observability plugin.
 final class ObservabilityPlugin extends Plugin {
+  final List<Instrumentation> _instrumentations = [];
   final PluginMetadata _metadata = const PluginMetadata(
     name: _launchDarklyObservabilityPluginName,
   );
 
+  ObservabilityPlugin() {
+    _instrumentations.add(LifecycleInstrumentation());
+  }
+
   @override
   void register(
     LDClient client,