Merge pull request #36 from Workiva/O11Y-1528

O11Y-1528 : update sdk to use api where possible

Author: rmconsole6-wk

README.md

@@ -20,71 +20,80 @@ The current options are:
 ### Span Exporters
 
 #### CollectorExporter
+
 The CollectorExporter requires a Uri of the opentelemetry-collector instance's trace collector.
-```
+
+```dart
 import 'package:opentelemetry/sdk.dart' as otel_sdk;
 
 final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));
 ```
 
 #### ConsoleExporter
+
 The ConsoleExporter has no requirements, and has no configuration options.
-```
+
+```dart
 import 'package:opentelemetry/sdk.dart' as otel_sdk;
 
 final exporter = otel_sdk.ConsoleExporter();
 ```
 
 ### Span Processors
 
-Next, you will need a at least one span processor.  A span processor is responsible for collectoring the spans you create and feeding them to the exporter.
+Next, you will need at least one span processor.  A span processor is responsible for collecting the spans you create and feeding them to the exporter.
 The current options are:
 
 | SpanProcessor | Description |
 | -------- | ----------- |
 | [BatchSpanProcessor](#batchspanprocessor) | Batches spans to be exported on a configured time interval. |
 | [SimpleSpanProcessor](#simplespanprocessor) | Executes the provided exporter immediately upon closing the span. |
 
-
 #### BatchSpanProcessor
+
 BatchSpanProcessors collect up to 2048 spans per interval, and executes the provided exporter on a timer.
 | Option | Description | Default |
 | ------ | ----------- | ------- |
 | maxExportBatchSize | At most, how many spans are processed per batch. | 512 |
 | scheduledDelay | How long to collect spans before processing them. | 5000 ms |
-```
+
+```dart
 import 'package:opentelemetry/sdk.dart' as otel_sdk;
 
 final exporter = otel_sdk.ConsoleExporter();
 final processor = otel_sdk.BatchSpanProcessor(exporter, scheduledDelay: 10000);
 ```
 
 #### SimpleSpanProcessor
+
 A SimpleSpanProcessor has no configuration options, and executes the exporter when each span is closed.
-```
+
+```dart
 import 'package:opentelemetry/sdk.dart' as otel_sdk;
 
 final exporter = otel_sdk.ConsoleExporter();
 final processor = otel_sdk.SimpleSpanProcessor(exporter);
 ```
 
 ### Tracer Provider
+
 A trace provider registers your span processors, and is responsible for managing any tracers.
 | Option | Description | Default |
 | ------ | ----------- | ------- |
 | processors | A list of SpanProcessors to register. | A [SimpleSpanProcessor](#simplespanprocessor) configured with a [ConsoleExporter](#consoleexporter). |
-```
+
+```dart
 import 'package:opentelemetry/sdk.dart' as otel_sdk;
 
 final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));
-final processor = otel_sdk.BatchSpanProcesor(exporter);
+final processor = otel_sdk.BatchSpanProcessor(exporter);
 
 // Send spans to a collector every 5 seconds
 final provider = otel_sdk.TracerProvider([processor]);
 
 // Optionally, multiple processors can be registered
 final provider = otel_sdk.TracerProvider([
-  otel_sdk.BatchSpanProcesor(otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'))),
+  otel_sdk.BatchSpanProcessor(otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'))),
   otel_sdk.SimpleSpanProcessor(otel_sdk.ConsoleExporter())
 ]);
 
@@ -97,14 +106,18 @@ final tracer = otel_sdk.globalTracerProvider.getTracer('instrumentation-name');
 ```
 
 ## Collecting Spans
+
 To start a span, execute `startSpan` on the tracer with the name of what you are tracing.  When complete, call `end` on the span.
-```
+
+```dart
 final span = tracer.startSpan('doingWork');
 ...
 span.end();
 ```
+
 To create children spans, you must set the parent span as "current", and execute work within `withContext`.
-```
+
+```dart
 final checkoutSpan = tracer.startSpan('checkout');
 withContext(setSpan(Context.current, checkoutSpan), () {
   final ringUpSpan = tracer.startSpan('ringUp');
@@ -121,7 +134,8 @@ checkoutSpan.end();
 ```
 
 To avoid needing to pass spans around as arguments to other functions, you can get the current span with `Context.current.span`.
-```
+
+```dart
 doWork() {
   Span parentSpan = Context.current.span;
 

lib/api.dart

@@ -2,15 +2,20 @@ 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/exporters/span_exporter.dart' show SpanExporter;
+export 'src/api/instrumentation_library.dart' show InstrumentationLibrary;
 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/resource/resource.dart' show Resource;
 export 'src/api/span_processors/span_processor.dart' show SpanProcessor;
 export 'src/api/trace/id_generator.dart' show IdGenerator;
+export 'src/api/trace/nonrecording_span.dart' show NonRecordingSpan;
+export 'src/api/trace/sampler.dart' show Sampler;
+export 'src/api/trace/sampling_result.dart' show Decision, SamplingResult;
 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/span_status.dart' show StatusCode;
+export 'src/api/trace/span_status.dart' show SpanStatus, StatusCode;
 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;

lib/sdk.dart

@@ -1,16 +1,27 @@
-export 'src/sdk/common/attribute.dart' show Attribute;
-export 'src/sdk/common/attributes.dart' show Attributes;
+export 'src/sdk/instrumentation_library.dart' show InstrumentationLibrary;
 export 'src/sdk/open_telemetry.dart'
-    show registerGlobalTracerProvider, globalTracerProvider;
+    show
+        registerGlobalTracerProvider,
+        globalTracerProvider,
+        registerGlobalTextMapPropagator,
+        globalTextMapPropagator;
 export 'src/sdk/resource/resource.dart' show Resource;
 export 'src/sdk/trace/exporters/collector_exporter.dart' show CollectorExporter;
 export 'src/sdk/trace/exporters/console_exporter.dart' show ConsoleExporter;
+export 'src/sdk/trace/id_generator.dart' show IdGenerator;
 export 'src/sdk/trace/propagation/w3c_trace_context_propagator.dart'
     show W3CTraceContextPropagator;
 export 'src/sdk/trace/samplers/always_off_sampler.dart' show AlwaysOffSampler;
 export 'src/sdk/trace/samplers/always_on_sampler.dart' show AlwaysOnSampler;
+export 'src/sdk/trace/samplers/parent_based_sampler.dart'
+    show ParentBasedSampler;
+export 'src/sdk/trace/samplers/sampling_result.dart' show SamplingResult;
+export 'src/sdk/trace/span.dart' show Span;
+export 'src/sdk/trace/span_context.dart' show SpanContext;
 export 'src/sdk/trace/span_processors/batch_processor.dart'
     show BatchSpanProcessor;
 export 'src/sdk/trace/span_processors/simple_processor.dart'
     show SimpleSpanProcessor;
+export 'src/sdk/trace/tracer.dart' show Tracer;
 export 'src/sdk/trace/tracer_provider.dart' show TracerProvider;
+export 'src/sdk/trace/trace_state.dart' show TraceState;

lib/src/api/common/attribute.dart

@@ -1,5 +1,5 @@
 /// A representation of a single piece of metadata attached to trace span.
-abstract class Attribute {
+class Attribute {
   final String key;
   final Object value;
 

lib/src/api/common/attributes.dart

@@ -1,27 +1,29 @@
 import 'attribute.dart';
 
 /// A representation of a collection of metadata attached to a trace span.
-abstract class Attributes {
-  /// Instantiate an empty Attributes.
-  Attributes.empty();
-
-  /// The size of this collection of Attributes.
-  int get length;
+class Attributes {
+  Map<String, Object> _attributes = {};
 
-  /// Whether this collection of Attributes is empty.
-  bool get isEmpty;
+  /// Instantiate an empty Attributes.
+  Attributes.empty() {
+    _attributes = {};
+  }
 
   /// Retrieve the value associated with the Attribute with key [key].
-  Object get(String key);
+  Object get(String key) => _attributes[key];
 
   /// Retrieve the keys of all Attributes in this collection.
-  Iterable<String> get keys;
+  Iterable<String> get keys => _attributes.keys;
 
   /// Add an Attribute [attribute].
   /// If an Attribute with the same key already exists, it will be overwritten.
-  void add(Attribute attribute);
+  void add(Attribute attribute) {
+    _attributes[attribute.key] = attribute.value;
+  }
 
   /// Add all Attributes in List [attributes].
   /// If an Attribute with the same key already exists, it will be overwritten.
-  void addAll(List<Attribute> attributes);
+  void addAll(List<Attribute> attributes) {
+    attributes.forEach(add);
+  }
 }

lib/src/api/context/context.dart

@@ -23,8 +23,7 @@
 /// OpenTelemetry SDKs.
 import 'dart:async';
 
-import 'package:opentelemetry/src/sdk/trace/span.dart';
-import 'package:opentelemetry/src/sdk/trace/span_context.dart';
+import '../../../api.dart' as api;
 
 /// [ContextKey] used to store spans in a [Context].
 final ContextKey spanKey = Context.createKey('OpenTelemetry Context Key SPAN');
@@ -65,20 +64,20 @@ class Context {
   Context setValue(ContextKey key, Object value) =>
       Context._(_zone.fork(zoneValues: {key: value}));
 
-  /// Returns a new [Context] created from this one with the given [Span]
+  /// Returns a new [Context] created from this one with the given [api.Span]
   /// set.
-  Context withSpan(Span span) => setValue(spanKey, span);
+  Context withSpan(api.Span span) => setValue(spanKey, span);
 
   /// Execute a function [fn] within this [Context] and return its result.
   R execute<R>(R Function() fn) => _zone.run(fn);
 
-  /// Get the [Span] attached to this [Context], or null if no such
-  /// [Span] exists.
-  Span get span => getValue(spanKey);
+  /// Get the [api.Span] attached to this [Context], or null if no such
+  /// [api.Span] exists.
+  api.Span get span => getValue(spanKey);
 
-  /// Get the [SpanContext] from this [Context], or null if no such
-  /// [SpanContext] exists.
-  SpanContext get spanContext => getValue(spanKey)?.spanContext;
+  /// Get the [api.SpanContext] from this [Context], or null if no such
+  /// [api.SpanContext] exists.
+  api.SpanContext get spanContext => getValue(spanKey)?.spanContext;
 }
 
 class ContextKey {

lib/src/api/exporters/span_exporter.dart

@@ -1,7 +1,7 @@
-import '../trace/span.dart';
+import '../../../api.dart' as api;
 
 abstract class SpanExporter {
-  void export(List<Span> spans);
+  void export(List<api.Span> spans);
 
   void shutdown();
 }

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

@@ -1,6 +1,6 @@
-import '../text_map_propagator.dart';
+import '../../../../api.dart' as api;
 
-/// Interface that allows a [TextMapPropagator] to read propagated fields from a carrier.
+/// Interface that allows a [api.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);

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

@@ -1,6 +1,6 @@
-import '../text_map_propagator.dart';
+import '../../../../api.dart' as api;
 
-/// Class that allows a [TextMapPropagator] to set propagated fields into a carrier.
+/// Class that allows a [api.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

@@ -1,6 +1,4 @@
-import '../context/context.dart';
-import 'extractors/text_map_getter.dart';
-import 'injectors/text_map_setter.dart';
+import '../../../api.dart' as api;
 
 /// A class responsible for performing the injection and extraction of a
 /// cross-cutting concern value as string key/values pairs into carriers that
@@ -9,7 +7,8 @@ import 'injectors/text_map_setter.dart';
 /// 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);
+  void inject(api.Context context, C carrier, api.TextMapSetter<C> setter);
 
-  Context extract(Context context, C carrier, TextMapGetter<C> getter);
+  api.Context extract(
+      api.Context context, C carrier, api.TextMapGetter<C> getter);
 }