Context propagation update (OTEP 66)

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

@@ -16,9 +16,12 @@
 
 package io.opentelemetry;
 
-import io.opentelemetry.distributedcontext.DefaultDistributedContextManager;
-import io.opentelemetry.distributedcontext.DistributedContextManager;
-import io.opentelemetry.distributedcontext.spi.DistributedContextManagerProvider;
+import io.opentelemetry.context.propagation.DefaultPropagators;
+import io.opentelemetry.context.propagation.Propagators;
+import io.opentelemetry.correlationcontext.CorrelationContextManager;
+import io.opentelemetry.correlationcontext.DefaultCorrelationContextManager;
+import io.opentelemetry.correlationcontext.spi.CorrelationContextManagerProvider;
+import io.opentelemetry.internal.Utils;
 import io.opentelemetry.metrics.DefaultMeterFactory;
 import io.opentelemetry.metrics.DefaultMeterFactoryProvider;
 import io.opentelemetry.metrics.Meter;
@@ -28,20 +31,21 @@
 import io.opentelemetry.trace.DefaultTracerFactoryProvider;
 import io.opentelemetry.trace.Tracer;
 import io.opentelemetry.trace.TracerFactory;
+import io.opentelemetry.trace.propagation.HttpTraceContext;
 import io.opentelemetry.trace.spi.TracerFactoryProvider;
 import java.util.ServiceLoader;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * This class provides a static global accessor for telemetry objects {@link Tracer}, {@link Meter}
- * and {@link DistributedContextManager}.
+ * and {@link CorrelationContextManager}.
  *
  * <p>The telemetry objects are lazy-loaded singletons resolved via {@link ServiceLoader} mechanism.
  *
  * @see TracerFactory
  * @see MeterFactoryProvider
- * @see DistributedContextManagerProvider
+ * @see CorrelationContextManagerProvider
  */
 @ThreadSafe
 public final class OpenTelemetry {
@@ -50,7 +54,10 @@ public final class OpenTelemetry {
 
   private final TracerFactory tracerFactory;
   private final MeterFactory meterFactory;
-  private final DistributedContextManager contextManager;
+  private final CorrelationContextManager contextManager;
+
+  private volatile Propagators propagators =
+      DefaultPropagators.builder().addHttpTextFormat(new HttpTraceContext()).build();
 
   /**
    * Returns a singleton {@link TracerFactory}.
@@ -77,18 +84,47 @@ public static MeterFactory getMeterFactory() {
   }
 
   /**
-   * Returns a singleton {@link DistributedContextManager}.
+   * Returns a singleton {@link CorrelationContextManager}.
    *
    * @return registered manager or default via {@link
-   *     DefaultDistributedContextManager#getInstance()}.
+   *     DefaultCorrelationContextManager#getInstance()}.
    * @throws IllegalStateException if a specified manager (via system properties) could not be
    *     found.
    * @since 0.1.0
    */
-  public static DistributedContextManager getDistributedContextManager() {
+  public static CorrelationContextManager getCorrelationContextManager() {
     return getInstance().contextManager;
   }
 
+  /**
+   * Returns a {@link Propagators} object, which can be used to access the set of registered
+   * propagators for each supported format.
+   *
+   * @return registered propagators container, defaulting to a {@link Propagators} object with
+   *     {@code HttpTraceContext} registered.
+   * @throws IllegalStateException if a specified manager (via system properties) could not be
+   *     found.
+   * @since 0.3.0
+   */
+  public static Propagators getPropagators() {
+    return getInstance().propagators;
+  }
+
+  /**
+   * Sets the {@link Propagators} object, which can be used to access the set of registered
+   * propagators for each supported format.
+   *
+   * @param propagators the {@link Propagators} object to be registered.
+   * @throws IllegalStateException if a specified manager (via system properties) could not be
+   *     found.
+   * @throws NullPointerException if {@code propagators} is {@code null}.
+   * @since 0.3.0
+   */
+  public static void setPropagators(Propagators propagators) {
+    Utils.checkNotNull(propagators, "propagators");
+    getInstance().propagators = propagators;
+  }
+
   /** Lazy loads an instance. */
   private static OpenTelemetry getInstance() {
     if (instance == null) {
@@ -113,12 +149,12 @@ private OpenTelemetry() {
         meterFactoryProvider != null
             ? meterFactoryProvider.create()
             : DefaultMeterFactoryProvider.getInstance().create();
-    DistributedContextManagerProvider contextManagerProvider =
-        loadSpi(DistributedContextManagerProvider.class);
+    CorrelationContextManagerProvider contextManagerProvider =
+        loadSpi(CorrelationContextManagerProvider.class);
     contextManager =
         contextManagerProvider != null
             ? contextManagerProvider.create()
-            : DefaultDistributedContextManager.getInstance();
+            : DefaultCorrelationContextManager.getInstance();
   }
 
   /**

api/src/main/java/io/opentelemetry/context/propagation/ContextUtils.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.opentelemetry.context.propagation;
+
+import io.grpc.Context;
+import io.opentelemetry.context.Scope;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Util methods/functionality to interact with the {@link io.grpc.Context}.
+ *
+ * <p>Users must interact with the current Context via the public APIs and avoid accessing this
+ * class directly.
+ *
+ * @since 0.1.0
+ */
+@Immutable
+public final class ContextUtils {
+  /**
+   * Sets the specified {@code Context} as {@code Context.current()}, returning a {@link Scope} to
+   * end its active state and restore the previous active {@code Context}.
+   *
+   * @param context the {@code Context} to be set as {@code Context.current()}.
+   * @return the {@link Scope} for the updated {@code Context}.
+   * @since 0.1.0
+   */
+  public static Scope withScopedContext(Context context) {
+    return new ContextInScope(context);
+  }
+
+  private static final class ContextInScope implements Scope {
+    private final Context context;
+    private final Context previous;
+
+    public ContextInScope(Context context) {
+      this.context = context;
+      this.previous = context.attach();
+    }
+
+    @Override
+    public void close() {
+      context.detach(previous);
+    }
+  }
+
+  private ContextUtils() {}
+}

api/src/main/java/io/opentelemetry/context/propagation/DefaultPropagators.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.opentelemetry.context.propagation;
+
+import io.grpc.Context;
+import io.opentelemetry.internal.Utils;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * {@code DefaultPropagators} is the default, built-in implementation of {@link Propagators}.
+ *
+ * <p>All the registered propagators are stored internally as a simple list, and are invoked
+ * synchronically upon injection and extraction.
+ *
+ * @since 0.3.0
+ */
+public final class DefaultPropagators implements Propagators {
+  private final HttpTextFormat textFormat;
+
+  @Override
+  public HttpTextFormat getHttpTextFormat() {
+    return textFormat;
+  }
+
+  /**
+   * Returns a {@link Propagators.Builder} to create a new {@link Propagators} object.
+   *
+   * <p>See {@link Propagators.Builder}.
+   *
+   * @return a {@link Propagators.Builder}.
+   * @since 0.3.0
+   */
+  public static Builder builder() {
+    return new DefaultBuilder();
+  }
+
+  private DefaultPropagators(HttpTextFormat textFormat) {
+    this.textFormat = textFormat;
+  }
+
+  private static final class DefaultBuilder implements Builder {
+    List<HttpTextFormat> textPropagators = new ArrayList<>();
+
+    @Override
+    public Builder addHttpTextFormat(HttpTextFormat textFormat) {
+      Utils.checkNotNull(textFormat, "textFormat");
+      textPropagators.add(textFormat);
+      return this;
+    }
+
+    @Override
+    public Propagators build() {
+      if (textPropagators.isEmpty()) {
+        return new DefaultPropagators(NoopHttpTextFormat.INSTANCE);
+      }
+
+      return new DefaultPropagators(new MultiHttpTextFormat(textPropagators));
+    }
+  }
+
+  private static final class MultiHttpTextFormat implements HttpTextFormat {
+    private final HttpTextFormat[] textPropagators;
+
+    private MultiHttpTextFormat(List<HttpTextFormat> textPropagators) {
+      this.textPropagators = new HttpTextFormat[textPropagators.size()];
+      textPropagators.toArray(this.textPropagators);
+    }
+
+    @Override
+    public List<String> fields() {
+      List<String> fields = new ArrayList<>();
+      for (int i = 0; i < textPropagators.length; i++) {
+        fields.addAll(textPropagators[i].fields());
+      }
+
+      return fields;
+    }
+
+    @Override
+    public <C> void inject(Context context, C carrier, Setter<C> setter) {
+      for (int i = 0; i < textPropagators.length; i++) {
+        textPropagators[i].inject(context, carrier, setter);
+      }
+    }
+
+    @Override
+    public <C> Context extract(Context context, C carrier, Getter<C> getter) {
+      for (int i = 0; i < textPropagators.length; i++) {
+        context = textPropagators[i].extract(context, carrier, getter);
+      }
+      return context;
+    }
+  }
+
+  private static final class NoopHttpTextFormat implements HttpTextFormat {
+    private static final NoopHttpTextFormat INSTANCE = new NoopHttpTextFormat();
+
+    @Override
+    public List<String> fields() {
+      return Collections.<String>emptyList();
+    }
+
+    @Override
+    public <C> void inject(Context context, C carrier, Setter<C> setter) {}
+
+    @Override
+    public <C> Context extract(Context context, C carrier, Getter<C> getter) {
+      return context;
+    }
+  }
+}