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

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,7 @@
+# Attach Detach Context Example
+
+This example demonstrates context propagation using the attach/detach context APIs through multiple zones.
+
+The example produces two traces represented by the following diagram:
+
+![./attach_detach_context.png](./attach_detach_context.png)

example/attach_detach_context/attach_detach_context.dart

@@ -0,0 +1,49 @@
+// 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;
+
+void main() {
+  final tp = TracerProviderBase(
+          processors: [SimpleSpanProcessor(ConsoleExporter())]),
+      tracer = tp.getTracer('instrumentation-name');
+
+  final span = tracer.startSpan('root-zone-attached-span')..end();
+  final token = attach(contextWithSpan(active, span));
+
+  final completer = Completer();
+
+  // zone A
+  zoneWithContext(active).run(() {
+    final span = tracer.startSpan('zone-a-attached-span')..end();
+    final context = contextWithSpan(active, span);
+
+    // zone B
+    zoneWithContext(context).run(() {
+      tracer.startSpan('zone-b-span').end();
+      completer.future.then((_) {
+        tracer.startSpan('zone-b-post-detach-span').end();
+      });
+    });
+
+    final token = attach(context);
+    tracer.startSpan('zone-a-attached-child-span').end();
+    if (!detach(token)) {
+      throw Exception('Failed to detach context');
+    }
+
+    tracer.startSpan('zone-a-post-detach-span').end();
+  });
+
+  if (!detach(token)) {
+    throw Exception('Failed to detach context');
+  }
+
+  completer.complete();
+
+  tracer.startSpan('root-zone-post-detach-span').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 the global getter, [active].
+  var context = active;
 
   // 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/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(active, span), carrier, MapSetter());
   await test(carrier);
   span.end();
 }
@@ -47,7 +43,7 @@ Future test(Map<String, String> carrier) async {
   globalTracerProvider
       .getTracer('instrumentation-name')
       .startSpan('test-span-1',
-          context: globalTextMapPropagator.extract(
-              globalContextManager.active, carrier, MapGetter()))
+          context:
+              globalTextMapPropagator.extract(active, carrier, MapGetter()))
       .end();
 }

lib/api.dart

@@ -6,16 +6,20 @@ export 'src/api/common/resource_attributes.dart' show ResourceAttributes;
 export 'src/api/common/semantic_attributes.dart' show SemanticAttributes;
 export 'src/api/context/context.dart'
     show
+        active,
+        attach,
         Context,
         ContextKey,
+        contextFromZone,
         contextWithSpan,
         contextWithSpanContext,
+        detach,
+        root,
         spanContextFromContext,
-        spanFromContext;
-export 'src/api/context/context_manager.dart' 
-    show
-        globalContextManager,
-        registerGlobalContextManager;
+        spanFromContext,
+        zoneWithContext;
+export 'src/api/context/context_manager.dart'
+    show globalContextManager, registerGlobalContextManager;
 export 'src/api/exporters/span_exporter.dart' show SpanExporter;
 export 'src/api/instrumentation_library.dart' show InstrumentationLibrary;
 export 'src/api/open_telemetry.dart'