Merge pull request #12 from michaelyeager-wf/myeager-wf/O11Y-1019

O11Y-1019: Inject and Extract context from a message to feed into span creation

Author: rmconsole7-wk

lib/api.dart

@@ -1,11 +1,17 @@
 export 'src/api/common/attribute.dart' show Attribute;
 export 'src/api/common/attributes.dart' show Attributes;
 export 'src/api/context/context.dart' show Context;
+export 'src/api/propagation/extractors/text_map_getter.dart' show TextMapGetter;
+export 'src/api/propagation/injectors/text_map_setter.dart' show TextMapSetter;
+export 'src/api/propagation/text_map_propagator.dart' show TextMapPropagator;
 export 'src/api/trace/context_utils.dart'
     show getSpan, getSpanContext, setSpan, withContext;
 export 'src/api/trace/id_generator.dart' show IdGenerator;
 export 'src/api/trace/span.dart' show Span;
 export 'src/api/trace/span_context.dart' show SpanContext;
+export 'src/api/trace/span_id.dart' show SpanId;
+export 'src/api/trace/trace_flags.dart' show TraceFlags;
+export 'src/api/trace/trace_id.dart' show TraceId;
 export 'src/api/trace/trace_state.dart' show TraceState;
 export 'src/api/trace/tracer.dart' show Tracer;
 export 'src/api/trace/tracer_provider.dart' show TracerProvider;

lib/src/api/propagation/extractors/text_map_getter.dart

@@ -0,0 +1,10 @@
+import '../text_map_propagator.dart';
+
+/// Interface that allows a [TextMapPropagator] to read propagated fields from a carrier.
+abstract class TextMapGetter<C> {
+  /// Returns all the keys in the given carrier.
+  Iterable<String> keys(C carrier);
+
+  /// Returns the first value of the given propagation [key] or returns null.
+  String get(C carrier, String key);
+}

lib/src/api/propagation/injectors/text_map_setter.dart

@@ -0,0 +1,7 @@
+import '../text_map_propagator.dart';
+
+/// Class that allows a [TextMapPropagator] to set propagated fields into a carrier.
+abstract class TextMapSetter<C> {
+  /// Sets [value] for [key] on [carrier].
+  void set(C carrier, String key, String value);
+}

lib/src/api/propagation/text_map_propagator.dart

@@ -0,0 +1,15 @@
+import '../context/context.dart';
+import 'extractors/text_map_getter.dart';
+import 'injectors/text_map_setter.dart';
+
+/// A class responsible for performing the injection and extraction of a
+/// cross-cutting concern value as string key/values pairs into carriers that
+/// travel across process boundaries.
+///
+/// See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md#textmap-propagator
+/// for full specification.
+abstract class TextMapPropagator<C> {
+  void inject(Context context, C carrier, TextMapSetter<C> setter);
+
+  Context extract(Context context, C carrier, TextMapGetter<C> getter);
+}

lib/src/api/trace/nonrecording_span.dart

@@ -0,0 +1,68 @@
+import 'package:fixnum/fixnum.dart';
+
+import '../../sdk/common/attributes.dart' as sdk_attributes;
+import '../../sdk/trace/span.dart';
+import '../../sdk/trace/span_context.dart' as sdk_spancontext;
+import '../../sdk/trace/span_id.dart';
+import '../common/attributes.dart';
+import 'noop_tracer.dart';
+import 'span.dart' as api;
+import 'span_context.dart';
+import 'span_status.dart';
+import 'tracer.dart';
+
+/// A class representing a [Span] which should not be sampled or recorded.
+///
+/// See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#wrapping-a-spancontext-in-a-span
+/// for more information.
+///
+/// This class should not be exposed to consumers and is used internally to wrap
+/// [SpanContext] being injected or extracted for external calls.
+class NonRecordingSpan extends Span implements api.Span {
+  final Attributes _attributes = sdk_attributes.Attributes.empty();
+  final SpanStatus _status = SpanStatus()..code = StatusCode.OK;
+  final Tracer _tracer = NoopTracer();
+  final SpanContext _spanContext;
+
+  NonRecordingSpan(this._spanContext)
+      : super('NON_RECORDING', _spanContext, null, [], NoopTracer());
+
+  @override
+  Attributes get attributes => _attributes;
+
+  @override
+  set attributes(Attributes attributes) {
+    return;
+  }
+
+  @override
+  void end() {
+    return;
+  }
+
+  @override
+  Int64 get endTime => Int64.ZERO;
+
+  @override
+  String get name => 'NON_RECORDING';
+
+  @override
+  SpanId get parentSpanId => null;
+
+  @override
+  void setStatus(StatusCode status, {String description}) {
+    return;
+  }
+
+  @override
+  sdk_spancontext.SpanContext get spanContext => _spanContext;
+
+  @override
+  Int64 get startTime => Int64.ZERO;
+
+  @override
+  SpanStatus get status => _status;
+
+  @override
+  Tracer get tracer => _tracer;
+}

lib/src/api/trace/noop_tracer.dart

@@ -0,0 +1,20 @@
+import '../../../api.dart' as api;
+import '../../sdk/trace/span_context.dart';
+import 'nonrecording_span.dart';
+import 'tracer.dart' as api;
+
+/// A [api.Tracer] class which yields [NonRecordingSpan]s and no-ops for most
+/// operations.
+class NoopTracer implements api.Tracer {
+  @override
+  String get name => 'NOOP';
+
+  @override
+  api.Span startSpan(String name,
+      {api.Context context, api.Attributes attributes}) {
+    final SpanContext parentContext = api.getSpanContext(context);
+
+    return NonRecordingSpan(
+        (parentContext.isValid) ? parentContext : SpanContext.invalid());
+  }
+}

lib/src/api/trace/sampler.dart

@@ -1,7 +1,7 @@
-import 'package:opentelemetry/src/api/context/context.dart';
-import 'package:opentelemetry/src/api/instrumentation_library.dart';
-import 'package:opentelemetry/src/api/trace/sampling_result.dart';
-import 'package:opentelemetry/src/api/trace/span.dart';
+import '../context/context.dart';
+import '../instrumentation_library.dart';
+import 'sampling_result.dart';
+import 'span.dart';
 
 /// Represents an entity which determines whether a [Span] should be sampled
 /// and sent for collection.

lib/src/api/trace/span.dart

@@ -1,8 +1,9 @@
 import 'package:fixnum/fixnum.dart';
-import 'span_status.dart';
-import '../common/attributes.dart';
 
+import '../common/attributes.dart';
 import 'span_context.dart';
+import 'span_id.dart';
+import 'span_status.dart';
 import 'tracer.dart';
 
 /// A representation of a single operation within a trace.
@@ -26,11 +27,15 @@ abstract class Span {
   Int64 get startTime;
 
   /// The parent span id.
-  List<int> get parentSpanId;
+  SpanId get parentSpanId;
 
   /// The name of the span.
   String get name;
 
+  /// Whether this Span is recording information like events with the
+  /// addEvent operation, status with setStatus, etc.
+  bool get isRecording;
+
   /// Sets the status to the [Span].
   ///
   /// If used, this will override the default [Span] status. Default status code

lib/src/api/trace/span_context.dart

@@ -1,13 +1,22 @@
+import 'span_id.dart';
+import 'trace_flags.dart';
+import 'trace_id.dart';
 import 'trace_state.dart';
 
 /// Representation of the context of the context of an individual span.
 abstract class SpanContext {
   /// Get the ID of the span.
-  List<int> get spanId;
+  SpanId get spanId;
 
   /// Get the ID of the trace the span is a part of.
-  List<int> get traceId;
+  TraceId get traceId;
+
+  /// Get flags (sampling, trace level, etc.) set for the trace the span is a
+  /// part of.
+  TraceFlags get traceFlags;
 
   /// Get the state of the entire trace.
   TraceState get traceState;
+
+  bool get isValid;
 }

lib/src/api/trace/span_id.dart

@@ -0,0 +1,21 @@
+import 'span.dart';
+
+/// Class representing an ID for a single [Span].
+/// See https://www.w3.org/TR/trace-context/#parent-id for full specification.
+abstract class SpanId {
+  static const SIZE_BITS = 16;
+  static const SIZE_BYTES = 8;
+  static final List<int> INVALID =
+      List<int>.filled(SIZE_BYTES, 0); // 0000000000000000
+  static final List<int> ROOT = [];
+
+  /// Retrieve this SpanId as a list of byte values.
+  List<int> get();
+
+  /// Whether this ID represents a valid [Span].
+  bool get isValid;
+
+  /// Retrieve this SpanId as a human-readable ID.
+  @override
+  String toString();
+}