feat: Add semantic conventions for feature flags. (#231)

## Summary

Adds semantic convention for feature flags.

## How did you test this change?

Unit testing.

Author: kinyoklion

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

@@ -0,0 +1,103 @@
+import 'dart:convert';
+
+import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
+import 'package:launchdarkly_flutter_observability/src/otel/stringable_attribute.dart';
+
+const _featureFlagEventName = 'feature_flag';
+const _featureFlagKeyAttr = '$_featureFlagEventName.key';
+
+// Feature flag set.
+const _featureFlagSetAttr = '$_featureFlagEventName.set';
+const _featureFlagSetIdAttr = '$_featureFlagSetAttr.id';
+
+// Feature flag provider.
+const _featureFlagProviderAttr = '$_featureFlagEventName.provider';
+const _featureFlagProviderNameAttr = '$_featureFlagProviderAttr.name';
+
+// Feature flag context.
+const _featureFlagContextAttr = '$_featureFlagEventName.context';
+const _featureFlagContextIdAttr = '$_featureFlagContextAttr.id';
+
+// Feature flag result.
+const _featureFlagResultAttr = '$_featureFlagEventName.result';
+const _featureFlagResultValueAttr = '$_featureFlagResultAttr.value';
+const _featureFlagResultVariationIndex =
+    '$_featureFlagResultAttr.variationIndex';
+const _featureFlagResultReasonAttr = '$_featureFlagResultAttr.reason';
+const _featureFlagResultReasonInExperimentAttr =
+    '$_featureFlagResultReasonAttr.inExperiment';
+
+final providerNameAttribute = StringableAttribute.fromString(
+  _featureFlagProviderNameAttr,
+  'LaunchDarkly',
+);
+
+String? _toJsonValue(LDValue value) {
+  try {
+    return jsonEncode(value.toDynamic());
+  } catch (_) {
+    // All LDValues must be JSON presentable, but this is for safety.
+    return null;
+  }
+}
+
+List<StringableAttribute> _getValueAttributes(LDEvaluationDetail<LDValue> detail) {
+  final attributes = <StringableAttribute>[];
+  final jsonValue = _toJsonValue(detail.value);
+  if (jsonValue != null) {
+    attributes.add(
+      StringableAttribute.fromString(_featureFlagResultValueAttr, jsonValue),
+    );
+  }
+  if (detail.variationIndex != null) {
+    attributes.add(
+      StringableAttribute.fromInt(
+        _featureFlagResultVariationIndex,
+        detail.variationIndex!,
+      ),
+    );
+  }
+  if (detail.reason != null && detail.reason!.inExperiment) {
+    attributes.add(
+      StringableAttribute.fromBoolean(
+        _featureFlagResultReasonInExperimentAttr,
+        detail.reason!.inExperiment,
+      ),
+    );
+  }
+  return attributes;
+}
+
+/// Class representing the feature flagging semantic convention with
+/// LaunchDarkly additions.
+class FeatureFlagConvention {
+  /// Get feature_flag event attributes.
+  static List<StringableAttribute> getEventAttributes({
+    required String key,
+    required LDEvaluationDetail<LDValue> detail,
+    LDContext? context,
+    String? environmentId,
+  }) {
+    List<StringableAttribute> attributes = [
+      providerNameAttribute,
+      StringableAttribute.fromString(_featureFlagKeyAttr, key),
+      ..._getValueAttributes(detail),
+    ];
+
+    if (context != null && context.valid) {
+      attributes.add(
+        StringableAttribute.fromString(_featureFlagContextIdAttr, context.canonicalKey),
+      );
+    }
+
+    if (environmentId != null) {
+      attributes.add(
+        StringableAttribute.fromString(_featureFlagSetIdAttr, environmentId!),
+      );
+    }
+    return attributes;
+  }
+
+  /// The name to use for the event.
+  static const eventName = _featureFlagEventName;
+}

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

@@ -0,0 +1,39 @@
+import 'package:opentelemetry/api.dart';
+
+/// Extended attribute class to add toString methods to attributes for
+/// error handling, testing, and debugging purposes.
+///
+/// This is an internal type not to be exposed to end users.
+/// I an attribute type were to be exposed, then it shouldn't indirectly expose
+/// the implementation Attribute type.
+final class StringableAttribute extends Attribute {
+  /// Create an Attribute from a String value.
+  StringableAttribute.fromString(super.key, super.value) : super.fromString();
+
+  /// Create an Attribute from a boolean value.
+  // ignore: avoid_positional_boolean_parameters
+  StringableAttribute.fromBoolean(super.key, super.value) : super.fromBoolean();
+
+  /// Create an Attribute from a double-precision floating-point value.
+  StringableAttribute.fromDouble(super.key, super.value) : super.fromDouble();
+
+  /// Create an Attribute from an integer value.
+  StringableAttribute.fromInt(super.key, super.value) : super.fromInt();
+
+  /// Create an Attribute from a list of String values.
+  StringableAttribute.fromStringList(super.key, super.value) : super.fromStringList();
+
+  /// Create an Attribute from a list of boolean values.
+  StringableAttribute.fromBooleanList(super.key, super.value) : super.fromBooleanList();
+
+  /// Create an Attribute from a list of double-precision floating-point values.
+  StringableAttribute.fromDoubleList(super.key, super.value) : super.fromDoubleList();
+
+  /// Create an Attribute from a list of integer values.
+  StringableAttribute.fromIntList(super.key, super.value) : super.fromIntList();
+
+  @override
+  String toString() {
+    return 'Attribute{key: $key, value: $value}';
+  }
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/pubspec.yaml

@@ -12,44 +12,11 @@ dependencies:
     flutter:
         sdk: flutter
 
+    opentelemetry: 0.18.10
+
+    launchdarkly_flutter_client_sdk: ^4.12.0
+
 dev_dependencies:
     flutter_test:
         sdk: flutter
     flutter_lints: ^5.0.0
-
-# For information on the generic Dart part of this file, see the
-# following page: https://dart.dev/tools/pub/pubspec
-
-# The following section is specific to Flutter packages.
-flutter:
-
-    # To add assets to your package, add an assets section, like this:
-    # assets:
-    #   - images/a_dot_burr.jpeg
-    #   - images/a_dot_ham.jpeg
-    #
-    # For details regarding assets in packages, see
-    # https://flutter.dev/to/asset-from-package
-    #
-    # An image asset can refer to one or more resolution-specific "variants", see
-    # https://flutter.dev/to/resolution-aware-images
-
-    # To add custom fonts to your package, add a fonts section here,
-    # in this "flutter" section. Each entry in this list should have a
-    # "family" key with the font family name, and a "fonts" key with a
-    # list giving the asset and other descriptors for the font. For
-    # example:
-    # fonts:
-    #   - family: Schyler
-    #     fonts:
-    #       - asset: fonts/Schyler-Regular.ttf
-    #       - asset: fonts/Schyler-Italic.ttf
-    #         style: italic
-    #   - family: Trajan Pro
-    #     fonts:
-    #       - asset: fonts/TrajanPro.ttf
-    #       - asset: fonts/TrajanPro_Bold.ttf
-    #         weight: 700
-    #
-    # For details regarding fonts in packages, see
-    # https://flutter.dev/to/font-from-package