feat: Add basic configuration. (#252)

## Summary

Adds basic configuration for flutter. At this point most of the
configuration is unused.

This gets the configuration in place, so the instrumentation
implementations can then build on that implementation.

## How did you test this change?

Manual testing. Unit tests.

## Are there any deployment considerations?

<!--
 Backend - Do we need to consider migrations or backfilling data?
-->

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds a configurable Observability plugin (app name/version, endpoints,
context namer), updates OTEL setup to use config and service attributes,
adjusts example, and adds tests.
> 
> - **Observability Plugin** (`src/plugin/observability_plugin.dart`)
> - Accepts configuration (applicationName, applicationVersion,
otlpEndpoint, backendUrl, contextFriendlyName) via new
`ObservabilityConfig`; passes config to `setup`.
> - **OTEL Setup** (`src/otel/setup.dart`)
> - `setup` now takes `ObservabilityConfig`, uses `config.otlpEndpoint`
for traces, and adds service attributes via `ServiceConvention`.
>   - Adds conversions import and traces path suffix.
> - **Service Attributes** (`src/otel/service_convention.dart`)
> - New helper to generate `service.name` and `service.version`
attributes.
> - **Configuration** (`src/plugin/observability_config.dart`)
> - New config class and `configWithDefaults` with defaults for OTLP and
backend URLs and optional app metadata/context namer.
> - **Example** (`example/lib/main.dart`)
> - Demonstrates `ObservabilityPlugin` configuration with
`applicationName` and `applicationVersion` from `GIT_SHA`.
> - **Tests** (`test/observability_config_test.dart`)
>   - Unit tests for config defaults and overrides.
> - **Dependencies** (`pubspec.yaml`)
>   - Adds `web` dependency.
> - **Misc**
>   - Minor import refactors in `lifecycle_instrumentation.dart`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
0f7e4fd. 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

@@ -1,5 +1,4 @@
 import 'dart:async';
-import 'dart:ui';
 
 import 'package:flutter/material.dart';
 import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
@@ -27,7 +26,18 @@ void main() {
           // If using android studio the `additional run args` option can include the correct --dart-define.
           CredentialSource.fromEnvironment(),
           AutoEnvAttributes.enabled,
-          plugins: [ObservabilityPlugin()],
+          plugins: [
+            ObservabilityPlugin(
+              applicationName: 'test-application',
+              // This could be a semantic version or a git commit hash.
+              // This demonstrates how to use an environment variable to set the hash.
+              // flutter build --dart-define GIT_SHA=$(git rev-parse HEAD) --dart-define LAUNCHDARKLY_MOBILE_KEY=<my-mobile-key>
+              applicationVersion: const String.fromEnvironment(
+                'GIT_SHA',
+                defaultValue: 'no-version',
+              ),
+            ),
+          ],
         ),
         LDContextBuilder().kind('user', 'bob').build(),
       );

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

@@ -1,9 +1,10 @@
 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 '../../api/span_status_code.dart';
 import '../../observe.dart';
+import '../instrumentation.dart';
+import './lifecycle_conventions.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';

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/otel/service_convention.dart

@@ -0,0 +1,20 @@
+import 'package:launchdarkly_flutter_observability/src/api/attribute.dart';
+
+const _attributeServiceName = 'service.name';
+const _attributeServiceVersion = 'service.version';
+
+class ServiceConvention {
+  static Map<String, Attribute> getAttributes({
+    String? serviceName,
+    String? serviceVersion,
+  }) {
+    final attributes = <String, Attribute>{};
+    if (serviceName != null) {
+      attributes[_attributeServiceName] = StringAttribute(serviceName);
+    }
+    if (serviceVersion != null) {
+      attributes[_attributeServiceVersion] = StringAttribute(serviceVersion);
+    }
+    return attributes;
+  }
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/otel/setup.dart

@@ -1,21 +1,30 @@
+import 'package:launchdarkly_flutter_observability/src/otel/conversions.dart';
+import 'package:launchdarkly_flutter_observability/src/otel/service_convention.dart';
+import 'package:launchdarkly_flutter_observability/src/plugin/observability_config.dart';
 import 'package:opentelemetry/api.dart'
     show registerGlobalTracerProvider, Attribute;
 import 'package:opentelemetry/sdk.dart'
     show BatchSpanProcessor, CollectorExporter, TracerProviderBase, Resource;
 
 const _highlightProjectIdAttr = 'highlight.project_id';
-const _defaultOtlpEndpoint =
-    'https://otel.observability.app.launchdarkly.com:4318';
-const _defaultOtlpTracesEndpoint = '$_defaultOtlpEndpoint/v1/traces';
+const _tracesSuffix = '/v1/traces';
 
-void setup(String sdkKey) {
+void setup(String sdkKey, ObservabilityConfig config) {
   final resourceAttributes = <Attribute>[
     Attribute.fromString(_highlightProjectIdAttr, sdkKey),
   ];
+  resourceAttributes.addAll(
+    convertAttributes(
+      ServiceConvention.getAttributes(
+        serviceName: config.applicationName,
+        serviceVersion: config.applicationVersion,
+      ),
+    ),
+  );
   final tracerProvider = TracerProviderBase(
     processors: [
       BatchSpanProcessor(
-        CollectorExporter(Uri.parse(_defaultOtlpTracesEndpoint)),
+        CollectorExporter(Uri.parse('${config.otlpEndpoint}$_tracesSuffix')),
       ),
     ],
     resource: Resource(resourceAttributes),

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

@@ -0,0 +1,54 @@
+import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
+
+const _defaultOtlpEndpoint =
+    'https://otel.observability.app.launchdarkly.com:4318';
+
+const _defaultBackendUrl = 'https://pub.observability.app.launchdarkly.com';
+
+// Implementation note: The final values with defaults should be included
+// in the configuration. This centralizes the assignment of defaults versus
+// having them in each location that requires them.
+
+final class ObservabilityConfig {
+  /// The configured OTLP endpoint.
+  final String otlpEndpoint;
+
+  /// The configured back-end URL.
+  final String backendUrl;
+
+  /// The name of the application.
+  final String? applicationName;
+
+  /// The version of the application.
+  ///
+  /// This is commonly a Git hash or a semantic version.
+  final String? applicationVersion;
+
+  /// Function for mapping context to a friendly name for use in the
+  /// observability UI.
+  final String? Function(LDContext context)? contextFriendlyName;
+
+  ObservabilityConfig({
+    this.applicationName,
+    this.applicationVersion,
+    required this.otlpEndpoint,
+    required this.backendUrl,
+    this.contextFriendlyName,
+  });
+}
+
+ObservabilityConfig configWithDefaults({
+  String? applicationName,
+  String? applicationVersion,
+  String? otlpEndpoint,
+  String? backendUrl,
+  String? Function(LDContext context)? contextFriendlyName,
+}) {
+  return ObservabilityConfig(
+    applicationName: applicationName,
+    applicationVersion: applicationVersion,
+    otlpEndpoint: otlpEndpoint ?? _defaultOtlpEndpoint,
+    backendUrl: backendUrl ?? _defaultBackendUrl,
+    contextFriendlyName: contextFriendlyName,
+  );
+}

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

@@ -6,6 +6,7 @@ import 'package:launchdarkly_flutter_observability/src/instrumentation/instrumen
 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';
+import 'package:launchdarkly_flutter_observability/src/plugin/observability_config.dart';
 
 import '../api/span.dart';
 import '../observe.dart';
@@ -73,7 +74,44 @@ final class ObservabilityPlugin extends Plugin {
     name: _launchDarklyObservabilityPluginName,
   );
 
-  ObservabilityPlugin() {
+  final ObservabilityConfig _config;
+
+  /// Construct an observability plugin with the given configuration.
+  ///
+  /// [applicationName] The name of the application.
+  /// [applicationVersion] The version of the application. This is commonly a
+  /// git SHA or semantic version.
+  /// [otlpEndpoint] The OTLP endpoint for reporting OpenTelemetry data. This
+  /// setting does not need to be used in most configurations.
+  /// [backendUrl] The back-end URL. This setting does not need to be used in
+  /// most configurations.
+  /// [contextFriendlyName] A function that returns a friendly name for a given
+  /// context. This name will be used to identify the session in the
+  /// observability UI.
+  /// ```dart
+  /// ObservabilityPlugin(contextFriendlyName: (LDContext context) {
+  ///   // If there is a user context with an email, then use that email.
+  ///   final email = context.get('user', AttributeReference('email'));
+  ///   if(email.stringValue().isNotEmpty) {
+  ///     return email.stringValue();
+  ///   }
+  ///   // If there is no email, then use the default name.
+  ///   return null;
+  /// })
+  /// ```
+  ObservabilityPlugin({
+    String? applicationName,
+    String? applicationVersion,
+    String? otlpEndpoint,
+    String? backendUrl,
+    String? Function(LDContext context)? contextFriendlyName,
+  }) : _config = configWithDefaults(
+         applicationName: applicationName,
+         applicationVersion: applicationVersion,
+         otlpEndpoint: otlpEndpoint,
+         backendUrl: backendUrl,
+         contextFriendlyName: contextFriendlyName,
+       ) {
     _instrumentations.add(LifecycleInstrumentation());
   }
 
@@ -82,7 +120,7 @@ final class ObservabilityPlugin extends Plugin {
     LDClient client,
     PluginEnvironmentMetadata environmentMetadata,
   ) {
-    setup(environmentMetadata.credential.value);
+    setup(environmentMetadata.credential.value, _config);
     super.register(client, environmentMetadata);
   }
 

sdk/@launchdarkly/launchdarkly_flutter_observability/pubspec.yaml

@@ -15,6 +15,7 @@ dependencies:
     opentelemetry: 0.18.10
 
     launchdarkly_flutter_client_sdk: ^4.12.0
+    web: ^1.1.1
 
 dev_dependencies:
     flutter_test:

sdk/@launchdarkly/launchdarkly_flutter_observability/test/observability_config_test.dart

@@ -0,0 +1,95 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
+import 'package:launchdarkly_flutter_observability/src/plugin/observability_config.dart';
+
+void main() {
+  group('configWithDefaults', () {
+    test('uses default OTLP endpoint when not provided', () {
+      final config = configWithDefaults();
+
+      expect(
+        config.otlpEndpoint,
+        'https://otel.observability.app.launchdarkly.com:4318',
+      );
+    });
+
+    test('uses default backend URL when not provided', () {
+      final config = configWithDefaults();
+
+      expect(
+        config.backendUrl,
+        'https://pub.observability.app.launchdarkly.com',
+      );
+    });
+
+    test('uses custom OTLP endpoint when provided', () {
+      final config = configWithDefaults(
+        otlpEndpoint: 'https://custom-otel.example.com:4318',
+      );
+
+      expect(config.otlpEndpoint, 'https://custom-otel.example.com:4318');
+    });
+
+    test('uses custom backend URL when provided', () {
+      final config = configWithDefaults(
+        backendUrl: 'https://custom-backend.example.com',
+      );
+
+      expect(config.backendUrl, 'https://custom-backend.example.com');
+    });
+
+    test('sets application name when provided', () {
+      final config = configWithDefaults(applicationName: 'MyApp');
+
+      expect(config.applicationName, 'MyApp');
+    });
+
+    test('sets application version when provided', () {
+      final config = configWithDefaults(applicationVersion: '1.2.3');
+
+      expect(config.applicationVersion, '1.2.3');
+    });
+
+    test('sets context friendly name function when provided', () {
+      String? friendlyNameFunc(LDContext context) => 'TestUser';
+
+      final config = configWithDefaults(contextFriendlyName: friendlyNameFunc);
+
+      expect(config.contextFriendlyName, friendlyNameFunc);
+    });
+
+    test('leaves application name null when not provided', () {
+      final config = configWithDefaults();
+
+      expect(config.applicationName, isNull);
+    });
+
+    test('leaves application version null when not provided', () {
+      final config = configWithDefaults();
+
+      expect(config.applicationVersion, isNull);
+    });
+
+    test('leaves context friendly name null when not provided', () {
+      final config = configWithDefaults();
+
+      expect(config.contextFriendlyName, isNull);
+    });
+
+    test('combines custom and default values', () {
+      final config = configWithDefaults(
+        applicationName: 'MyApp',
+        applicationVersion: '1.0.0',
+        backendUrl: 'https://custom.example.com',
+      );
+
+      expect(config.applicationName, 'MyApp');
+      expect(config.applicationVersion, '1.0.0');
+      expect(config.backendUrl, 'https://custom.example.com');
+      expect(
+        config.otlpEndpoint,
+        'https://otel.observability.app.launchdarkly.com:4318',
+      );
+    });
+  });
+}