More user-friendly Context util classes

QUICKSTART.md

@@ -48,7 +48,7 @@ To create a basic span, you only need to specify the name of the span.
 The start and end time of the span is automatically set by the OpenTelemetry SDK.
 ```java
 Span span = tracer.spanBuilder("my span").startSpan();
-try (Scope scope = tracer.withSpan(span)) {
+try (Scope scope = CurrentContext.withSpan(span)) {
 	// your use case
 	...
 } catch (Throwable t) {
@@ -85,7 +85,7 @@ The OpenTelemetry API offers also an automated way to propagate the `parentSpan`
 ```java
 void a() {
   Span parentSpan = tracer.spanBuilder("a").startSpan();
-  try(Scope scope = tracer.withSpan(parentSpan)){
+  try(Scope scope = CurrentContext.withSpan(parentSpan)){
     b();
   } finally {
     parentSpan.end();
@@ -186,7 +186,7 @@ HttpTextFormat.Setter<HttpURLConnection> setter =
 
 URL url = new URL("http://127.0.0.1:8080/resource");
 Span outGoing = tracer.spanBuilder("/resource").setSpanKind(Span.Kind.CLIENT).startSpan();
-try (Scope scope = tracer.withSpan(outGoing)) {
+try (Scope scope = CurrentContext.withSpan(outGoing)) {
   // Semantic Convention.
   // (Observe that to set these, Span does not *need* to be the current instance.)
   outGoing.setAttribute("http.method", "GET");
@@ -222,7 +222,7 @@ public void handle(HttpExchange httpExchange) {
   Context extractedContext = OpenTelemetry.getPropagators().getHttpTextFormat()
         .extract(Context.current(), httpExchange, getter);
   Span serverSpan = null;
-  try (Scope scope = ContextUtils.withScopedContext(extractedContext)) {
+  try (Scope scope = CurrentContext.withContext(extractedContext)) {
     // Automatically use the extracted SpanContext as parent.
     serverSpan = tracer.spanBuilder("/resource").setSpanKind(Span.Kind.SERVER)
         .startSpan();

api/src/jmh/java/io/opentelemetry/trace/DefaultTracerBenchmarks.java

@@ -16,6 +16,8 @@
 
 package io.opentelemetry.trace;
 
+import io.opentelemetry.scope.DefaultScopeManager;
+import io.opentelemetry.scope.ScopeManager;
 import java.util.concurrent.TimeUnit;
 import javax.annotation.Nullable;
 import org.openjdk.jmh.annotations.Benchmark;
@@ -33,7 +35,8 @@
 @State(Scope.Thread)
 public class DefaultTracerBenchmarks {
 
-  private final Tracer tracer = DefaultTracer.getInstance();
+  private final ScopeManager scopeManager = DefaultScopeManager.getInstance();
+  private final Tracer tracer = new DefaultTracer(scopeManager);
   @Nullable private Span span = null;
 
   /** Benchmark the full span lifecycle. */
@@ -45,7 +48,7 @@ public class DefaultTracerBenchmarks {
   @Warmup(iterations = 5, time = 1)
   public void measureFullSpanLifecycle() {
     span = tracer.spanBuilder("span").startSpan();
-    io.opentelemetry.context.Scope ignored = tracer.withSpan(span);
+    io.opentelemetry.scope.Scope ignored = scopeManager.withSpan(span);
     try {
       // no-op
     } finally {
@@ -72,7 +75,7 @@ public void measureSpanBuilding() {
   @OutputTimeUnit(TimeUnit.NANOSECONDS)
   @Warmup(iterations = 5, time = 1)
   public void measureScopeLifecycle() {
-    io.opentelemetry.context.Scope ignored = tracer.withSpan(span);
+    io.opentelemetry.scope.Scope ignored = scopeManager.withSpan(span);
     try {
       // no-op
     } finally {
@@ -87,7 +90,7 @@ public void measureScopeLifecycle() {
   @OutputTimeUnit(TimeUnit.NANOSECONDS)
   @Warmup(iterations = 5, time = 1)
   public void measureGetCurrentSpan() {
-    tracer.getCurrentSpan();
+    scopeManager.getSpan();
   }
 
   @TearDown(Level.Iteration)

api/src/jmh/java/io/opentelemetry/trace/propagation/HttpTraceContextInjectBenchmark.java

@@ -19,12 +19,12 @@
 import io.grpc.Context;
 import io.opentelemetry.context.propagation.HttpTextFormat.Setter;
 import io.opentelemetry.trace.DefaultSpan;
+import io.opentelemetry.trace.Span;
 import io.opentelemetry.trace.SpanContext;
 import io.opentelemetry.trace.SpanId;
 import io.opentelemetry.trace.TraceFlags;
 import io.opentelemetry.trace.TraceId;
 import io.opentelemetry.trace.TraceState;
-import io.opentelemetry.trace.TracingContextUtils;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;
@@ -93,7 +93,7 @@ private static SpanContext createTestSpanContext(String traceId, String spanId)
   private static List<Context> createContexts(List<SpanContext> spanContexts) {
     List<Context> contexts = new ArrayList<>();
     for (SpanContext context : spanContexts) {
-      contexts.add(TracingContextUtils.withSpan(DefaultSpan.create(context), Context.ROOT));
+      contexts.add(Span.Key.put(DefaultSpan.create(context), Context.ROOT));
     }
     return contexts;
   }

api/src/main/java/io/opentelemetry/OpenTelemetry.java

@@ -29,6 +29,8 @@
 import io.opentelemetry.metrics.Meter;
 import io.opentelemetry.metrics.MeterProvider;
 import io.opentelemetry.metrics.spi.MetricsProvider;
+import io.opentelemetry.scope.DefaultScopeManager;
+import io.opentelemetry.scope.ScopeManager;
 import io.opentelemetry.trace.DefaultTraceProvider;
 import io.opentelemetry.trace.DefaultTracerProvider;
 import io.opentelemetry.trace.Tracer;
@@ -58,14 +60,16 @@ public final class OpenTelemetry {
   private final TracerProvider tracerProvider;
   private final MeterProvider meterProvider;
   private final CorrelationContextManager contextManager;
+  private final ScopeManager scopeManager;
 
   private volatile ContextPropagators propagators =
       DefaultContextPropagators.builder().addHttpTextFormat(new HttpTraceContext()).build();
 
   /**
    * Returns a singleton {@link TracerProvider}.
    *
-   * @return registered TracerProvider or default via {@link DefaultTracerProvider#getInstance()}.
+   * @return registered TracerProvider or default via {@link
+   *     DefaultTracerProvider#DefaultTracerProvider(ScopeManager)}.
    * @throws IllegalStateException if a specified TracerProvider (via system properties) could not
    *     be found.
    * @since 0.1.0
@@ -160,6 +164,11 @@ public static CorrelationContextManager getCorrelationContextManager() {
     return getInstance().contextManager;
   }
 
+  // TODO (trask) javadoc
+  public static ScopeManager getScopeManager() {
+    return getInstance().scopeManager;
+  }
+
   /**
    * Returns a {@link ContextPropagators} object, which can be used to access the set of registered
    * propagators for each supported format.
@@ -202,11 +211,13 @@ private static OpenTelemetry getInstance() {
   }
 
   private OpenTelemetry() {
+    // TODO (trask) should this come from SPI?
+    scopeManager = DefaultScopeManager.getInstance();
     TraceProvider traceProvider = loadSpi(TraceProvider.class);
     this.tracerProvider =
         traceProvider != null
-            ? new ObfuscatedTracerProvider(traceProvider.create())
-            : DefaultTraceProvider.getInstance().create();
+            ? new ObfuscatedTracerProvider(traceProvider.create(scopeManager))
+            : DefaultTraceProvider.getInstance().create(scopeManager);
 
     MetricsProvider metricsProvider = loadSpi(MetricsProvider.class);
     meterProvider =
@@ -217,8 +228,8 @@ private OpenTelemetry() {
         loadSpi(CorrelationContextManagerProvider.class);
     contextManager =
         contextManagerProvider != null
-            ? contextManagerProvider.create()
-            : DefaultCorrelationContextManagerProvider.getInstance().create();
+            ? contextManagerProvider.create(scopeManager)
+            : DefaultCorrelationContextManagerProvider.getInstance().create(scopeManager);
   }
 
   /**

api/src/main/java/io/opentelemetry/correlationcontext/CorrelationContext.java

@@ -16,6 +16,8 @@
 
 package io.opentelemetry.correlationcontext;
 
+import io.grpc.Context;
+import io.opentelemetry.scope.ScopeManager;
 import java.util.Collection;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
@@ -31,6 +33,7 @@
  */
 @Immutable
 public interface CorrelationContext {
+
   /**
    * Returns an immutable collection of the entries in this {@code CorrelationContext}. Order of
    * entries is not guaranteed.
@@ -50,6 +53,22 @@ public interface CorrelationContext {
   @Nullable
   EntryValue getEntryValue(EntryKey entryKey);
 
+  // TODO (trask) javadoc class and methods
+  class Key {
+    private static final Context.Key<CorrelationContext> KEY =
+        Context.keyWithDefault("CorrelationContext", EmptyCorrelationContext.getInstance());
+
+    public static CorrelationContext get(Context context) {
+      return KEY.get(context);
+    }
+
+    public static Context put(CorrelationContext correlationContext, Context context) {
+      return context.withValue(KEY, correlationContext);
+    }
+
+    private Key() {}
+  }
+
   /**
    * Builder for the {@link CorrelationContext} class.
    *
@@ -58,8 +77,8 @@ public interface CorrelationContext {
   interface Builder {
     /**
      * Sets the parent {@link CorrelationContext} to use. If no parent is provided, the value of
-     * {@link CorrelationContextManager#getCurrentContext()} at {@link #build()} time will be used
-     * as parent, unless {@link #setNoParent()} was called.
+     * {@link ScopeManager#getCorrelationContext()} at {@link #build()} time will be used as parent,
+     * unless {@link #setNoParent()} was called.
      *
      * <p>This <b>must</b> be used to create a {@link CorrelationContext} when manual Context
      * propagation is used.
@@ -77,8 +96,7 @@ interface Builder {
     /**
      * Sets the option to become a root {@link CorrelationContext} with no parent. If <b>not</b>
      * called, the value provided using {@link #setParent(CorrelationContext)} or otherwise {@link
-     * CorrelationContextManager#getCurrentContext()} at {@link #build()} time will be used as
-     * parent.
+     * ScopeManager#getCorrelationContext()} at {@link #build()} time will be used as parent.
      *
      * @return this.
      * @since 0.1.0

api/src/main/java/io/opentelemetry/correlationcontext/CorrelationContextManager.java

@@ -16,7 +16,6 @@
 
 package io.opentelemetry.correlationcontext;
 
-import io.opentelemetry.context.Scope;
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
@@ -27,39 +26,19 @@
  * implementation-dependent {@link CorrelationContext}s.
  *
  * <p>Implementations may have different constraints and are free to convert entry contexts to their
- * own subtypes. This means callers cannot assume the {@link #getCurrentContext() current context}
- * is the same instance as the one {@link #withContext(CorrelationContext) placed into scope}.
+ * own subtypes.
  *
  * @since 0.1.0
  */
+// TODO (trask) update class javadoc
 @ThreadSafe
 public interface CorrelationContextManager {
 
-  /**
-   * Returns the current {@code CorrelationContext}.
-   *
-   * @return the current {@code CorrelationContext}.
-   * @since 0.1.0
-   */
-  CorrelationContext getCurrentContext();
-
   /**
    * Returns a new {@code Builder}.
    *
    * @return a new {@code Builder}.
    * @since 0.1.0
    */
   CorrelationContext.Builder contextBuilder();
-
-  /**
-   * Enters the scope of code where the given {@code CorrelationContext} is in the current context
-   * (replacing the previous {@code CorrelationContext}) and returns an object that represents that
-   * scope. The scope is exited when the returned object is closed.
-   *
-   * @param distContext the {@code CorrelationContext} to be set as the current context.
-   * @return an object that defines a scope where the given {@code CorrelationContext} is set as the
-   *     current context.
-   * @since 0.1.0
-   */
-  Scope withContext(CorrelationContext distContext);
 }