feat: Add basic flutter plugin. (#233)

## Summary

Adds a basic observability plugin for flutter. This doesn't have any
configuration and only support basic tracing.

There are wrappers for spans, attributes, and the span kind because
there isn't an official open telemetry implementation for dart. We don't
want to encourage importing the API package as is supported in most
other SDKs.

We may want to consider vendoring the otel code and keeping it internal
to limit the potential breakage if we change implementations.

## 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?
-->

Author: kinyoklion

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

@@ -1,5 +1,6 @@
-/// A Calculator.
-class Calculator {
-  /// Returns [value] plus 1.
-  int addOne(int value) => value + 1;
-}
+export 'src/plugin/observability_plugin.dart' show ObservabilityPlugin;
+export 'src/observe.dart' show Observe;
+export 'src/api/attribute.dart' show Attribute;
+export 'src/api/span.dart' show Span;
+export 'src/api/span_kind.dart' show SpanKind;
+export 'src/api/span_status_code.dart' show SpanStatusCode;

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/api/attribute.dart

@@ -0,0 +1,147 @@
+/// Base class representing an open telemetry attribute.
+///
+/// Attributes may be a boolean, integer, double, string, list of booleans,
+/// list of integers, list of doubles, or list of strings.
+///
+/// There is a type-safe attribute constructor for each attribute type, or
+/// alternatively [Attribute.fromDynamic] can be used. If the dynamic attribute
+/// is not a compatible type, then the attribute will not be added.
+/// ```dart
+/// span.setAttribute('my-integer', IntAttribute(42));
+/// span.setAttribute('my-string', StringAttribute('test'));
+/// span.setAttribute('from-dynamic-value', Attribute.fromDynamic(value));
+/// ```
+sealed class Attribute {
+  factory Attribute.fromDynamic(dynamic value) {
+    if (value is bool) {
+      return BooleanAttribute(value);
+    }
+    if (value is int) {
+      return IntAttribute(value);
+    }
+    if (value is double) {
+      return DoubleAttribute(value);
+    }
+    if (value is String) {
+      return StringAttribute(value);
+    }
+    if (value is List<String>) {
+      return StringListAttribute(value);
+    }
+    if (value is List<double>) {
+      return DoubleListAttribute(value);
+    }
+    if (value is List<int>) {
+      return IntListAttribute(value);
+    }
+    if (value is List<bool>) {
+      return BooleanListAttribute(value);
+    }
+    return InvalidAttribute._internal();
+  }
+  const Attribute._internal();
+}
+
+/// When using [fromDynamic] it is possible to get a value that cannot be
+/// represented as an attribute. When this happens an [InvalidAttribute] will
+/// be created. This attribute will be omitted from otel data.
+final class InvalidAttribute extends Attribute {
+  const InvalidAttribute._internal() : super._internal();
+
+  @override
+  String toString() => 'InvalidAttribute()';
+}
+
+// Implementation note: Most of the constructors are non-const because the list
+// versions cannot be const. It is a bit safer to make them non-const, because
+// if we made them const, and later they needed to not be const, then removing
+// the const would be a breaking change.
+// The constructor for the InvalidAttribute and the base Attribute are internal
+// only, so they are safe to make const.
+
+/// An integer attribute.
+final class IntAttribute extends Attribute {
+  final int value;
+  IntAttribute(this.value) : super._internal();
+
+  @override
+  String toString() => 'IntAttribute{value: $value}';
+}
+
+/// A double attribute.
+final class DoubleAttribute extends Attribute {
+  final double value;
+
+  DoubleAttribute(this.value) : super._internal();
+
+  @override
+  String toString() => 'DoubleAttribute{value: $value}';
+}
+
+/// A boolean attribute.
+final class BooleanAttribute extends Attribute {
+  final bool value;
+
+  BooleanAttribute(this.value) : super._internal();
+
+  @override
+  String toString() => 'BooleanAttribute{value: $value}';
+}
+
+/// A string attribute.
+final class StringAttribute extends Attribute {
+  final String value;
+
+  StringAttribute(this.value) : super._internal();
+
+  @override
+  String toString() => 'StringAttribute{value: $value}';
+}
+
+/// An attribute containing a list of strings.
+final class StringListAttribute extends Attribute {
+  late final List<String> value;
+
+  StringListAttribute(List<String> input)
+    : value = List.unmodifiable(input),
+      super._internal();
+
+  @override
+  String toString() => 'StringListAttribute{value: $value}';
+}
+
+/// An attribute containing a list of doubles.
+final class DoubleListAttribute extends Attribute {
+  late final List<double> value;
+
+  DoubleListAttribute(List<double> input)
+    : value = List.unmodifiable(input),
+      super._internal();
+
+  @override
+  String toString() => 'DoubleListAttribute{value: $value}';
+}
+
+/// An attribute containing a list of integers.
+final class IntListAttribute extends Attribute {
+  late final List<int> value;
+
+  IntListAttribute(List<int> input)
+    : value = List.unmodifiable(input),
+      super._internal();
+
+  @override
+  String toString() => 'IntListAttribute{value: $value}';
+}
+
+/// An attribute containing a list of booleans.
+final class BooleanListAttribute extends Attribute {
+  late final List<bool> value;
+
+  BooleanListAttribute(List<bool> input)
+    : value = List.unmodifiable(input),
+      super._internal();
+
+  @override
+  String toString() => 'BooleanListAttribute{value: $value}';
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/api/span.dart

@@ -0,0 +1,78 @@
+import 'package:launchdarkly_flutter_observability/src/api/attribute.dart';
+import 'package:opentelemetry/api.dart' as otel;
+
+import '../otel/conversions.dart';
+import 'span_status_code.dart';
+
+/// Represents a single operation within a trace.
+final class Span {
+  final otel.Span _innerSpan;
+
+  // The context token type is not exported from the opentelemetry package.
+  final dynamic _contextToken;
+
+  Span._internal(this._innerSpan, this._contextToken);
+
+  void end() {
+    otel.Context.detach(_contextToken);
+    _innerSpan.end();
+  }
+
+  /// Set an attribute on the span.
+  ///
+  /// The attribute may be a boolean, integer, double, string, list of booleans,
+  /// list of integers, list of doubles, or list of strings.
+  ///
+  /// There is a type-safe attribute constructor for each attribute type, or
+  /// alternatively [Attribute.fromDynamic] can be used. If the dynamic attribute
+  /// is not a compatible type, then the attribute will not be added.
+  ///
+  /// ```dart
+  /// span.setAttribute('my-integer', IntAttribute(42));
+  /// span.setAttribute('my-string', StringAttribute('test'));
+  /// span.setAttribute('from-dynamic-value', Attribute.fromDynamic(value));
+  /// ```
+  void setAttribute(String name, Attribute attribute) {
+    final otelAttribute = convertAttribute(name, attribute);
+    if (otelAttribute != null) {
+      _innerSpan.setAttribute(otelAttribute);
+    }
+  }
+
+  /// Set attributes on the span.
+  /// For details about attributes refer to [setAttribute].
+  void setAttributes(Map<String, Attribute> attributes) {
+    _innerSpan.setAttributes(convertAttributes(attributes));
+  }
+
+  /// Record information about an exception that happened during this span.
+  void recordException(
+    dynamic exception, {
+    StackTrace stackTrace = StackTrace.empty,
+    Map<String, Attribute>? attributes,
+  }) {
+    // The otel library supports an "escaped" attribute, but attribute is
+    // deprecated and no longer recommended, so we aren't exporting it.
+    _innerSpan.recordException(
+      exception,
+      stackTrace: stackTrace,
+      attributes: convertAttributes(attributes),
+    );
+  }
+
+  /// Add an event to the span with the given attributes.
+  void addEvent(String name, {Map<String, Attribute>? attributes}) {
+    _innerSpan.addEvent(name, attributes: convertAttributes(attributes));
+  }
+
+  void setStatus(SpanStatusCode status) {
+    _innerSpan.setStatus(convertSpanStatus(status));
+  }
+}
+
+/// Wrap a span with a LaunchDarkly specific API type.
+///
+/// Not for export.
+Span wrapSpan(otel.Span span, dynamic token) {
+  return Span._internal(span, token);
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/api/span_kind.dart

@@ -0,0 +1,23 @@
+/// The kind of the span.
+enum SpanKind {
+  /// Default value. Indicates that the span represents an internal operation
+  /// within an application, as opposed to an operations with remote parents or
+  /// children.
+  internal,
+
+  /// Indicates that the span describes a request to a remote service where the
+  /// client awaits a response.
+  client,
+
+  /// Indicates that the span covers server-side handling of a remote request
+  /// while the client awaits a response.
+  server,
+
+  ///  Indicates that the span describes the initiation or scheduling of a local
+  ///  or remote operation.
+  producer,
+
+  /// Indicates that the span represents the processing of an operation
+  /// initiated by a producer, where the producer does not wait for the outcome.
+  consumer,
+}

sdk/@launchdarkly/launchdarkly_flutter_observability/lib/src/api/span_status_code.dart

@@ -0,0 +1,11 @@
+/// The status of the span.
+enum SpanStatusCode {
+  /// The status has not been set. This is the default status.
+  unset,
+
+  /// The operation the span represents encountered an error.
+  error,
+
+  /// The operation the span represents completed successfully.
+  ok,
+}

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

@@ -0,0 +1,29 @@
+import 'package:launchdarkly_flutter_observability/src/api/attribute.dart';
+import 'package:opentelemetry/api.dart' as otel;
+import 'api/span.dart';
+import 'api/span_kind.dart';
+import 'otel/conversions.dart';
+
+const _launchDarklyTracerName = 'launchdarkly-observability';
+
+/// Singleton used to access observability features.
+final class Observe {
+  /// Start a span with the given name and optional attributes.
+  static Span startSpan(
+    String name, {
+    SpanKind kind = SpanKind.internal,
+    Map<String, Attribute>? attributes,
+  }) {
+    final tracer = otel.globalTracerProvider.getTracer(_launchDarklyTracerName);
+    final span = tracer.startSpan(
+      name,
+      kind: convertKind(kind),
+      attributes: convertAttributes(attributes),
+    );
+    final token = otel.Context.attach(
+      otel.contextWithSpan(otel.Context.current, span),
+    );
+
+    return wrapSpan(span, token);
+  }
+}

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

@@ -0,0 +1,71 @@
+import 'package:launchdarkly_flutter_observability/src/api/span_kind.dart';
+import 'package:launchdarkly_flutter_observability/src/api/span_status_code.dart';
+import 'package:opentelemetry/api.dart' as otel;
+
+import '../api/attribute.dart';
+
+/// Not for export.
+otel.Attribute? convertAttribute(String name, Attribute attribute) {
+  switch (attribute) {
+    case IntAttribute():
+      return otel.Attribute.fromInt(name, attribute.value);
+    case DoubleAttribute():
+      return otel.Attribute.fromDouble(name, attribute.value);
+    case BooleanAttribute():
+      return otel.Attribute.fromBoolean(name, attribute.value);
+    case StringAttribute():
+      return otel.Attribute.fromString(name, attribute.value);
+    case StringListAttribute():
+      return otel.Attribute.fromStringList(name, attribute.value);
+    case DoubleListAttribute():
+      return otel.Attribute.fromDoubleList(name, attribute.value);
+    case IntListAttribute():
+      return otel.Attribute.fromIntList(name, attribute.value);
+    case BooleanListAttribute():
+      return otel.Attribute.fromBooleanList(name, attribute.value);
+    case InvalidAttribute():
+      return null;
+  }
+}
+
+/// Not for export.
+List<otel.Attribute> convertAttributes(Map<String, Attribute>? attributes) {
+  if (attributes == null) {
+    return [];
+  }
+  final otelAttributes = <otel.Attribute>[];
+  attributes.forEach((name, attribute) {
+    final otelAttribute = convertAttribute(name, attribute);
+    if (otelAttribute != null) {
+      otelAttributes.add(otelAttribute);
+    }
+  });
+  return otelAttributes;
+}
+
+/// Not for export.
+otel.SpanKind convertKind(SpanKind kind) {
+  switch (kind) {
+    case SpanKind.server:
+      return otel.SpanKind.server;
+    case SpanKind.client:
+      return otel.SpanKind.client;
+    case SpanKind.producer:
+      return otel.SpanKind.producer;
+    case SpanKind.consumer:
+      return otel.SpanKind.consumer;
+    case SpanKind.internal:
+      return otel.SpanKind.internal;
+  }
+}
+
+otel.StatusCode convertSpanStatus(SpanStatusCode status) {
+  switch (status) {
+    case SpanStatusCode.unset:
+      return otel.StatusCode.unset;
+    case SpanStatusCode.error:
+      return otel.StatusCode.error;
+    case SpanStatusCode.ok:
+      return otel.StatusCode.ok;
+  }
+}