PPI-203 : deprecate context manager and implement attach/detach APIs

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.18.6](https://github.com/Workiva/opentelemetry-dart/tree/0.18.6) (2024-08-15)
+
+[Full Changelog](https://github.com/Workiva/opentelemetry-dart/compare/0.18.5...0.18.6)
+
+**Merged pull requests:**
+
+- Make registerGlobalContextManager public API [\#183](https://github.com/Workiva/opentelemetry-dart/pull/183) ([jonathancampbell-wk](https://github.com/jonathancampbell-wk))
+- O11Y-4831: Use test URL in test [\#181](https://github.com/Workiva/opentelemetry-dart/pull/181) ([kennytrytek-wf](https://github.com/kennytrytek-wf))
+
 ## [0.18.5](https://github.com/Workiva/opentelemetry-dart/tree/0.18.5) (2024-08-01)
 
 [Full Changelog](https://github.com/Workiva/opentelemetry-dart/compare/0.18.4...0.18.5)

README.md

@@ -68,7 +68,7 @@ void main(List<String> args) {
 
 In order to parent spans, context must be propagated. Propagation can be achieved by manually passing an instance of `Context` or by using Dart [`Zones`](https://dart.dev/libraries/async/zones).
 
-See the [noop context manager example](./example/noop_context_manager.dart) and [zone context manager example](./example/zone_context_manager.dart) for more information.
+See the [attach detach context example](./example/attach_detach_context)for more information.
 
 ### Inter-process
 

example/attach_detach_context/README.md

@@ -0,0 +1,13 @@
+# Attach Detach Context Example
+
+This example demonstrates context propagation using the attach/detach context APIs.
+
+The example produces two traces represented by the following diagram:
+
+```mermaid
+flowchart LR
+  r1[Root 1 Span] --> c[Child Span]
+  c --> g1[Grandchild 1 Span]
+  c --> g2[Grandchild 2 Span]
+  r2[Root 2 Span]
+```

example/attach_detach_context/attach_detach_context.dart

@@ -0,0 +1,42 @@
+// Copyright 2021-2022 Workiva.
+// Licensed under the Apache License, Version 2.0. Please see https://github.com/Workiva/opentelemetry-dart/blob/master/LICENSE for more information
+
+import 'package:opentelemetry/api.dart';
+import 'package:opentelemetry/sdk.dart'
+    show ConsoleExporter, SimpleSpanProcessor, TracerProviderBase;
+
+void main() {
+  final tp = TracerProviderBase(
+          processors: [SimpleSpanProcessor(ConsoleExporter())]),
+      tracer = tp.getTracer('instrumentation-name');
+
+  // Attach the root span to the current context (the root context) making the
+  // span the current span until it is detached.
+  final rootToken = Context.attach(
+      contextWithSpan(Context.current, tracer.startSpan('root-1')..end()));
+
+  // Starting a child span will automatically parent the span to the span held
+  // by the attached context.
+  final child1 = tracer.startSpan('child')..end();
+  final context = contextWithSpan(Context.current, child1);
+
+  // Starting a span doesn't automatically attach the span. So to make the
+  // parent span actually parent a span, its context needs to be attached.
+  final childToken = Context.attach(context);
+  tracer.startSpan('grandchild-1').end();
+  if (!Context.detach(childToken)) {
+    throw Exception('Failed to detach context');
+  }
+
+  // Alternatively, manually specifying the desired parent context avoids the
+  // need to attach and detach the context.
+  tracer.startSpan('grandchild-2', context: context).end();
+
+  if (!Context.detach(rootToken)) {
+    throw Exception('Failed to detach context');
+  }
+
+  // Since the previous root span context was detached, spans will no longer be
+  // automatically parented.
+  tracer.startSpan('root-2').end();
+}

example/main.dart

@@ -1,6 +1,8 @@
 // Copyright 2021-2022 Workiva.
 // Licensed under the Apache License, Version 2.0. Please see https://github.com/Workiva/opentelemetry-dart/blob/master/LICENSE for more information
 
+import 'dart:async';
+
 import 'package:opentelemetry/api.dart';
 import 'package:opentelemetry/sdk.dart';
 
@@ -28,20 +30,21 @@ final tracer = provider.getTracer('instrumentation-name');
 
 /// Demonstrates creating a trace with a parent and child span.
 void main() async {
-  // The current active span is available via the global context manager.
-  var context = globalContextManager.active;
+  // The current active context is available via a static getter.
+  var context = Context.current;
 
   // A trace starts with a root span which has no parent.
   final parentSpan = tracer.startSpan('parent-span');
 
   // A new context can be created in order to propagate context manually.
   context = contextWithSpan(context, parentSpan);
 
-  // The traceContext and traceContextSync functions will automatically
+  // The [traceContext] and [traceContextSync] functions will automatically
   // propagate context, capture errors, and end the span.
-  await traceContext(
-      'child-span', (_context) => Future.delayed(Duration(milliseconds: 100)),
-      context: context);
+  await traceContext('child-span', (_) {
+    tracer.startSpan('grandchild-span').end();
+    return Future.delayed(Duration(milliseconds: 100));
+  }, context: context, tracer: tracer);
 
   // Spans must be ended or they will not be exported.
   parentSpan.end();

example/stream_context/README.md

@@ -0,0 +1,18 @@
+# Stream Context Propagation Example
+
+This example demonstrates context propagation over a `Stream` or `StreamController`.
+
+The example produces three traces represented by the following diagram:
+
+```mermaid
+flowchart LR
+  subgraph a[Zone A]
+    direction LR
+    ap[Zone A Parent Span] --> ac[Zone A Child Span]
+    r[New Root Span]
+    ec[Event Child Span]
+  end
+  ep[Event Parent Span] --> ec
+```
+
+Note: When registering a stream listener, A stream listener callback is executed in the Zone where the callback was registered. This can lead to long running traces if the stream gets an event long after it was registered. To avoid this issue, the `trace` and `traceSync` functions will attach and detach the span they create before and after invoking the callback given to them.

example/stream_context/stream_context.dart

@@ -0,0 +1,37 @@
+// Copyright 2021-2022 Workiva.
+// Licensed under the Apache License, Version 2.0. Please see https://github.com/Workiva/opentelemetry-dart/blob/master/LICENSE for more information
+
+import 'dart:async';
+
+import 'package:opentelemetry/api.dart';
+import 'package:opentelemetry/sdk.dart'
+    show ConsoleExporter, SimpleSpanProcessor, TracerProviderBase;
+
+mixin EventContext {
+  final Context context = Context.current;
+}
+
+class MyEvent with EventContext {
+  MyEvent();
+}
+
+void main() async {
+  final tp = TracerProviderBase(
+          processors: [SimpleSpanProcessor(ConsoleExporter())]),
+      tracer = tp.getTracer('instrumentation-name');
+
+  final controller = StreamController<MyEvent>();
+
+  traceSync('zone-a-parent', () {
+    tracer.startSpan('zone-a-child').end();
+
+    controller.stream.listen((e) {
+      tracer.startSpan('new-root').end();
+      tracer.startSpan('event-child', context: e.context).end();
+    });
+  }, tracer: tracer);
+
+  traceSync('event-parent', () => controller.add(MyEvent()), tracer: tracer);
+
+  await controller.close();
+}

example/w3c_context_propagation.dart

@@ -4,7 +4,6 @@
 import 'package:opentelemetry/api.dart';
 import 'package:opentelemetry/sdk.dart'
     show ConsoleExporter, SimpleSpanProcessor, TracerProviderBase;
-import 'package:opentelemetry/src/experimental_api.dart' show NoopContextManager;
 
 class MapSetter implements TextMapSetter<Map> {
   @override
@@ -30,15 +29,12 @@ void main(List<String> args) async {
       TracerProviderBase(processors: [SimpleSpanProcessor(ConsoleExporter())]);
   registerGlobalTracerProvider(tp);
 
-  final cm = NoopContextManager();
-  registerGlobalContextManager(cm);
-
   final tmp = W3CTraceContextPropagator();
   registerGlobalTextMapPropagator(tmp);
 
   final span = tp.getTracer('instrumentation-name').startSpan('test-span-0');
   final carrier = <String, String>{};
-  tmp.inject(contextWithSpan(cm.active, span), carrier, MapSetter());
+  tmp.inject(contextWithSpan(Context.current, span), carrier, MapSetter());
   await test(carrier);
   span.end();
 }
@@ -48,6 +44,6 @@ Future test(Map<String, String> carrier) async {
       .getTracer('instrumentation-name')
       .startSpan('test-span-1',
           context: globalTextMapPropagator.extract(
-              globalContextManager.active, carrier, MapGetter()))
+              Context.current, carrier, MapGetter()))
       .end();
 }

lib/api.dart

@@ -11,7 +11,8 @@ export 'src/api/context/context.dart'
         contextWithSpan,
         contextWithSpanContext,
         spanContextFromContext,
-        spanFromContext;
+        spanFromContext,
+        zone;
 export 'src/api/context/context_manager.dart'
     show globalContextManager, registerGlobalContextManager;
 export 'src/api/exporters/span_exporter.dart' show SpanExporter;