MultiTracePropagator implementation (#1339)

Author: carlosalberto

api/src/main/java/io/opentelemetry/trace/propagation/HttpTraceContext.java

@@ -125,6 +125,10 @@ private static <C> void injectImpl(SpanContext spanContext, C carrier, Setter<C>
     checkNotNull(getter, "getter");
 
     SpanContext spanContext = extractImpl(carrier, getter);
+    if (!spanContext.isValid()) {
+      return context;
+    }
+
     return TracingContextUtils.withSpan(DefaultSpan.create(spanContext), context);
   }
 

api/src/test/java/io/opentelemetry/trace/propagation/HttpTraceContextTest.java

@@ -30,6 +30,7 @@
 import io.opentelemetry.trace.TraceId;
 import io.opentelemetry.trace.TraceState;
 import io.opentelemetry.trace.TracingContextUtils;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -162,6 +163,15 @@ public void inject_NotSampledContext_WithTraceState() {
             TRACESTATE_NOT_DEFAULT_ENCODING);
   }
 
+  @Test
+  public void extract_Nothing() {
+    // Context remains untouched.
+    assertThat(
+            httpTraceContext.extract(
+                Context.current(), Collections.<String, String>emptyMap(), Map::get))
+        .isSameInstanceAs(Context.current());
+  }
+
   @Test
   public void extract_SampledContext() {
     Map<String, String> carrier = new LinkedHashMap<>();

extensions/trace_propagators/src/main/java/io/opentelemetry/extensions/trace/propagation/AwsXRayPropagator.java

@@ -125,6 +125,10 @@ public <C> Context extract(Context context, C carrier, Getter<C> getter) {
     Objects.requireNonNull(getter, "getter");
 
     SpanContext spanContext = getSpanContextFromHeader(carrier, getter);
+    if (!spanContext.isValid()) {
+      return context;
+    }
+
     return TracingContextUtils.withSpan(DefaultSpan.create(spanContext), context);
   }
 

extensions/trace_propagators/src/main/java/io/opentelemetry/extensions/trace/propagation/B3PropagatorExtractorMultipleHeaders.java

@@ -39,6 +39,10 @@ public <C> Context extract(Context context, C carrier, HttpTextFormat.Getter<C>
     Objects.requireNonNull(carrier, "carrier");
     Objects.requireNonNull(getter, "getter");
     SpanContext spanContext = getSpanContextFromMultipleHeaders(carrier, getter);
+    if (!spanContext.isValid()) {
+      return context;
+    }
+
     return TracingContextUtils.withSpan(DefaultSpan.create(spanContext), context);
   }
 

extensions/trace_propagators/src/main/java/io/opentelemetry/extensions/trace/propagation/B3PropagatorExtractorSingleHeader.java

@@ -38,6 +38,10 @@ public <C> Context extract(Context context, C carrier, HttpTextFormat.Getter<C>
     Objects.requireNonNull(carrier, "carrier");
     Objects.requireNonNull(getter, "getter");
     SpanContext spanContext = getSpanContextFromSingleHeader(carrier, getter);
+    if (!spanContext.isValid()) {
+      return context;
+    }
+
     return TracingContextUtils.withSpan(DefaultSpan.create(spanContext), context);
   }
 

extensions/trace_propagators/src/main/java/io/opentelemetry/extensions/trace/propagation/JaegerPropagator.java

@@ -110,6 +110,9 @@ public <C> Context extract(Context context, C carrier, Getter<C> getter) {
     Objects.requireNonNull(getter, "getter");
 
     SpanContext spanContext = getSpanContextFromHeader(carrier, getter);
+    if (!spanContext.isValid()) {
+      return context;
+    }
 
     return TracingContextUtils.withSpan(DefaultSpan.create(spanContext), context);
   }

extensions/trace_propagators/src/main/java/io/opentelemetry/extensions/trace/propagation/TraceMultiPropagator.java

@@ -0,0 +1,184 @@
+/*
+ * Copyright 2020, 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.extensions.trace.propagation;
+
+import io.grpc.Context;
+import io.opentelemetry.context.propagation.HttpTextFormat;
+import io.opentelemetry.trace.TracingContextUtils;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * A propagator designed to inject and extract multiple trace {@code HttpTextFormat} propagators,
+ * intendended for backwards compatibility with existing services using different formats. It works
+ * in a stack-fashion, starting with the last registered propagator, to the first one.
+ *
+ * <p>Upon injection, this propagator invokes {@code HttpTextFormat#inject()} for every registered
+ * trace propagator. This will result in the carrier containing all the registered formats.
+ *
+ * <p>Upon extraction, this propagator invokes {@code HttpTextFormat#extract()} for every registered
+ * trace propagator, returning immediately when a successful extraction happened.
+ *
+ * <pre>{@code
+ * HttpTextFormat traceFormats = TraceMultiPropagator.builder()
+ *   .addPropagator(new MyCustomTracePropagator())
+ *   .addPropagator(new JaegerPropagator())
+ *   .addPropagator(new HttpTraceContext())
+ *   .build();
+ * // Register it in the global propagators:
+ * OpenTelemetry.setPropagators(
+ *     DefaultContextPropagators.builder()
+ *       .addHttpTextFormat(traceFormats)
+ *       .build());
+ * ...
+ * // Extraction will be performed in reverse  order, i.e. starting with the last
+ * // registered propagator (HttpTraceContext in this example).
+ * Context context = OpenTelemetry.getPropagators().getHttpTextFormat()
+ *   .extract(context, carrier, carrierGetter);
+ * }</pre>
+ *
+ * @since 0.6.0
+ */
+@Immutable
+public class TraceMultiPropagator implements HttpTextFormat {
+  private final HttpTextFormat[] propagators;
+  private final List<String> propagatorsFields;
+
+  private TraceMultiPropagator(List<HttpTextFormat> propagatorList) {
+    this.propagators = new HttpTextFormat[propagatorList.size()];
+    propagatorList.toArray(this.propagators);
+
+    List<String> fields = new ArrayList<>();
+    for (HttpTextFormat propagator : propagators) {
+      fields.addAll(propagator.fields());
+    }
+    this.propagatorsFields = Collections.unmodifiableList(fields);
+  }
+
+  /**
+   * Returns a {@link TraceMultiPropagator.Builder} to create a new {@link TraceMultiPropagator}
+   * object.
+   *
+   * @return a {@link TraceMultiPropagator.Builder}.
+   * @since 0.6.0
+   */
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  /**
+   * The propagation fields defined in all the registered propagators. The returned list will be
+   * read-only.
+   *
+   * @return list of fields defined in all the registered propagators.
+   * @since 0.6.0
+   */
+  @Override
+  public List<String> fields() {
+    return propagatorsFields;
+  }
+
+  /**
+   * Injects the value downstream invoking all the registered propagators, starting with the last
+   * one.
+   *
+   * @param context the {@code Context} containing the value to be injected.
+   * @param carrier holds propagation fields. For example, an outgoing message or http request.
+   * @param setter invoked for each propagation key to add or remove.
+   * @param <C> carrier of propagation fields, such as an http request
+   * @since 0.6.0
+   */
+  @Override
+  public <C> void inject(Context context, C carrier, Setter<C> setter) {
+    for (int i = propagators.length - 1; i >= 0; i--) {
+      propagators[i].inject(context, carrier, setter);
+    }
+  }
+
+  /**
+   * Extracts the value from upstream invoking all the registered propagators, starting with the
+   * last one. Iterating over the propagators will stop and return immediately upon the first
+   * successful extraction.
+   *
+   * @param context the {@code Context} used to store the extracted value.
+   * @param carrier holds propagation fields. For example, an outgoing message or http request.
+   * @param getter invoked for each propagation key to get.
+   * @param <C> carrier of propagation fields, such as an http request.
+   * @return the {@code Context} containing the extracted value.
+   * @since 0.6.0
+   */
+  @Override
+  public <C> Context extract(Context context, C carrier, Getter<C> getter) {
+    for (int i = propagators.length - 1; i >= 0; i--) {
+      context = propagators[i].extract(context, carrier, getter);
+      if (isSpanContextExtracted(context)) {
+        break;
+      }
+    }
+
+    return context;
+  }
+
+  private static boolean isSpanContextExtracted(Context context) {
+    return TracingContextUtils.getSpanWithoutDefault(context) != null;
+  }
+
+  /**
+   * {@link Builder} is used to construct a new {@code TraceMultiPropagator} object with the
+   * specified propagators.
+   *
+   * @since 0.6.0
+   */
+  public static class Builder {
+    private final List<HttpTextFormat> propagators;
+
+    private Builder() {
+      propagators = new ArrayList<>();
+    }
+
+    /**
+     * Adds a {@link HttpTextFormat} trace propagator.
+     *
+     * <p>Registered propagators will be invoked in reverse order, starting with the last propagator
+     * to the first one.
+     *
+     * @param propagator the propagator to be added.
+     * @return this.
+     * @throws NullPointerException if {@code propagator} is {@code null}.
+     * @since 0.6.0
+     */
+    public Builder addPropagator(HttpTextFormat propagator) {
+      Objects.requireNonNull(propagator, "propagator");
+
+      propagators.add(propagator);
+      return this;
+    }
+
+    /**
+     * Builds a new {@code TraceMultiPropagator} with the specified propagators.
+     *
+     * @return the newly created {@code TraceMultiPropagator} instance.
+     * @since 0.6.0
+     */
+    public TraceMultiPropagator build() {
+      return new TraceMultiPropagator(propagators);
+    }
+  }
+}

extensions/trace_propagators/src/test/java/io/opentelemetry/extensions/trace/propagation/AwsXRayPropagatorTest.java

@@ -28,6 +28,7 @@
 import io.opentelemetry.trace.TraceId;
 import io.opentelemetry.trace.TraceState;
 import io.opentelemetry.trace.TracingContextUtils;
+import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import javax.annotation.Nullable;
@@ -111,6 +112,15 @@ public void inject_WithTraceState() {
             "Root=1-8a3c60f7-d188f8fa79d48a391a778fa6;Parent=53995c3f42cd8ad8;Sampled=0");
   }
 
+  @Test
+  public void extract_Nothing() {
+    // Context remains untouched.
+    assertThat(
+            xrayPropagator.extract(
+                Context.current(), Collections.<String, String>emptyMap(), Map::get))
+        .isSameInstanceAs(Context.current());
+  }
+
   @Test
   public void extract_SampledContext() {
     Map<String, String> carrier = new LinkedHashMap<>();

extensions/trace_propagators/src/test/java/io/opentelemetry/extensions/trace/propagation/B3PropagatorTest.java

@@ -28,6 +28,7 @@
 import io.opentelemetry.trace.TraceId;
 import io.opentelemetry.trace.TraceState;
 import io.opentelemetry.trace.TracingContextUtils;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -132,6 +133,15 @@ public void inject_NotSampledContext() {
     assertThat(carrier).containsEntry(B3Propagator.SAMPLED_HEADER, "0");
   }
 
+  @Test
+  public void extract_Nothing() {
+    // Context remains untouched.
+    assertThat(
+            b3Propagator.extract(
+                Context.current(), Collections.<String, String>emptyMap(), Map::get))
+        .isSameInstanceAs(Context.current());
+  }
+
   @Test
   public void extract_SampledContext_Int() {
     Map<String, String> carrier = new LinkedHashMap<>();
@@ -296,6 +306,15 @@ public void inject_NotSampledContext_SingleHeader() {
             B3Propagator.COMBINED_HEADER, TRACE_ID_BASE16 + "-" + SPAN_ID_BASE16 + "-" + "0");
   }
 
+  @Test
+  public void extract_Nothing_SingleHeader() {
+    // Context remains untouched.
+    assertThat(
+            b3PropagatorSingleHeader.extract(
+                Context.current(), Collections.<String, String>emptyMap(), Map::get))
+        .isSameInstanceAs(Context.current());
+  }
+
   @Test
   public void extract_SampledContext_Int_SingleHeader() {
     Map<String, String> carrier = new LinkedHashMap<>();

extensions/trace_propagators/src/test/java/io/opentelemetry/extensions/trace/propagation/JaegerPropagatorTest.java

@@ -35,6 +35,7 @@
 import io.opentelemetry.trace.TracingContextUtils;
 import java.io.UnsupportedEncodingException;
 import java.net.URLEncoder;
+import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import javax.annotation.Nullable;
@@ -152,6 +153,15 @@ public void inject_NotSampledContext() {
                 TRACE_ID_BASE16, SPAN_ID_BASE16, DEPRECATED_PARENT_SPAN, "0"));
   }
 
+  @Test
+  public void extract_Nothing() {
+    // Context remains untouched.
+    assertThat(
+            jaegerPropagator.extract(
+                Context.current(), Collections.<String, String>emptyMap(), Map::get))
+        .isSameInstanceAs(Context.current());
+  }
+
   @Test
   public void extract_EmptyHeaderValue() {
     Map<String, String> invalidHeaders = new LinkedHashMap<>();