Merge remote-tracking branch 'aosp/upstream-master' into merge am: dd3cabeacc

am: 6fbc3cf5a1

Change-Id: I11b0ec1cf561d2a14da78e444b1594f167787fe6

3 files changed, 298 insertions, 0 deletions

diff --git a/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/B3Format.java b/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/B3Format.java
new file mode 100644
index 00000000..d928d93c
--- /dev/null
+++ b/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/B3Format.java
@@ -0,0 +1,113 @@
+/*
+ * Copyright 2017, OpenCensus 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.opencensus.implcore.trace.propagation;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.annotations.VisibleForTesting;
+import io.opencensus.trace.SpanContext;
+import io.opencensus.trace.SpanId;
+import io.opencensus.trace.TraceId;
+import io.opencensus.trace.TraceOptions;
+import io.opencensus.trace.Tracestate;
+import io.opencensus.trace.propagation.SpanContextParseException;
+import io.opencensus.trace.propagation.TextFormat;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/*>>>
+import org.checkerframework.checker.nullness.qual.NonNull;
+*/
+
+/**
+ * Implementation of the B3 propagation protocol. See <a
+ * href=https://github.com/openzipkin/b3-propagation>b3-propagation</a>.
+ */
+final class B3Format extends TextFormat {
+  private static final Tracestate TRACESTATE_DEFAULT = Tracestate.builder().build();
+  @VisibleForTesting static final String X_B3_TRACE_ID = "X-B3-TraceId";
+  @VisibleForTesting static final String X_B3_SPAN_ID = "X-B3-SpanId";
+  @VisibleForTesting static final String X_B3_PARENT_SPAN_ID = "X-B3-ParentSpanId";
+  @VisibleForTesting static final String X_B3_SAMPLED = "X-B3-Sampled";
+  @VisibleForTesting static final String X_B3_FLAGS = "X-B3-Flags";
+  private static final List<String> FIELDS =
+      Collections.unmodifiableList(
+          Arrays.asList(
+              X_B3_TRACE_ID, X_B3_SPAN_ID, X_B3_PARENT_SPAN_ID, X_B3_SAMPLED, X_B3_FLAGS));
+
+  // Used as the upper TraceId.SIZE hex characters of the traceID. B3-propagation used to send
+  // TraceId.SIZE hex characters (8-bytes traceId) in the past.
+  private static final String UPPER_TRACE_ID = "0000000000000000";
+  // Sampled value via the X_B3_SAMPLED header.
+  private static final String SAMPLED_VALUE = "1";
+  // "Debug" sampled value.
+  private static final String FLAGS_VALUE = "1";
+
+  @Override
+  public List<String> fields() {
+    return FIELDS;
+  }
+
+  @Override
+  public <C /*>>> extends @NonNull Object*/> void inject(
+      SpanContext spanContext, C carrier, Setter<C> setter) {
+    checkNotNull(spanContext, "spanContext");
+    checkNotNull(setter, "setter");
+    checkNotNull(carrier, "carrier");
+    setter.put(carrier, X_B3_TRACE_ID, spanContext.getTraceId().toLowerBase16());
+    setter.put(carrier, X_B3_SPAN_ID, spanContext.getSpanId().toLowerBase16());
+    if (spanContext.getTraceOptions().isSampled()) {
+      setter.put(carrier, X_B3_SAMPLED, SAMPLED_VALUE);
+    }
+  }
+
+  @Override
+  public <C /*>>> extends @NonNull Object*/> SpanContext extract(C carrier, Getter<C> getter)
+      throws SpanContextParseException {
+    checkNotNull(carrier, "carrier");
+    checkNotNull(getter, "getter");
+    try {
+      TraceId traceId;
+      String traceIdStr = getter.get(carrier, X_B3_TRACE_ID);
+      if (traceIdStr != null) {
+        if (traceIdStr.length() == TraceId.SIZE) {
+          // This is an 8-byte traceID.
+          traceIdStr = UPPER_TRACE_ID + traceIdStr;
+        }
+        traceId = TraceId.fromLowerBase16(traceIdStr);
+      } else {
+        throw new SpanContextParseException("Missing X_B3_TRACE_ID.");
+      }
+      SpanId spanId;
+      String spanIdStr = getter.get(carrier, X_B3_SPAN_ID);
+      if (spanIdStr != null) {
+        spanId = SpanId.fromLowerBase16(spanIdStr);
+      } else {
+        throw new SpanContextParseException("Missing X_B3_SPAN_ID.");
+      }
+      TraceOptions traceOptions = TraceOptions.DEFAULT;
+      if (SAMPLED_VALUE.equals(getter.get(carrier, X_B3_SAMPLED))
+          || FLAGS_VALUE.equals(getter.get(carrier, X_B3_FLAGS))) {
+        traceOptions = TraceOptions.builder().setIsSampled(true).build();
+      }
+      return SpanContext.create(traceId, spanId, traceOptions, TRACESTATE_DEFAULT);
+    } catch (IllegalArgumentException e) {
+      throw new SpanContextParseException("Invalid input.", e);
+    }
+  }
+}
diff --git a/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/BinaryFormatImpl.java b/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/BinaryFormatImpl.java
new file mode 100644
index 00000000..233fbd31
--- /dev/null
+++ b/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/BinaryFormatImpl.java
@@ -0,0 +1,148 @@
+/*
+ * Copyright 2017, OpenCensus 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.opencensus.implcore.trace.propagation;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.annotations.VisibleForTesting;
+import io.opencensus.trace.SpanContext;
+import io.opencensus.trace.SpanId;
+import io.opencensus.trace.TraceId;
+import io.opencensus.trace.TraceOptions;
+import io.opencensus.trace.Tracestate;
+import io.opencensus.trace.propagation.BinaryFormat;
+import io.opencensus.trace.propagation.SpanContextParseException;
+
+/**
+ * Implementation of the {@link BinaryFormat}.
+ *
+ * <p>BinaryFormat format:
+ *
+ * <ul>
+ *   <li>Binary value: &lt;version_id&gt;&lt;version_format&gt;
+ *   <li>version_id: 1-byte representing the version id.
+ *   <li>For version_id = 0:
+ *       <ul>
+ *         <li>version_format: &lt;field&gt;&lt;field&gt;
+ *         <li>field_format: &lt;field_id&gt;&lt;field_format&gt;
+ *         <li>Fields:
+ *             <ul>
+ *               <li>TraceId: (field_id = 0, len = 16, default = &#34;0000000000000000&#34;) -
+ *                   16-byte array representing the trace_id.
+ *               <li>SpanId: (field_id = 1, len = 8, default = &#34;00000000&#34;) - 8-byte array
+ *                   representing the span_id.
+ *               <li>TraceOptions: (field_id = 2, len = 1, default = &#34;0&#34;) - 1-byte array
+ *                   representing the trace_options.
+ *             </ul>
+ *         <li>Fields MUST be encoded using the field id order (smaller to higher).
+ *         <li>Valid value example:
+ *             <ul>
+ *               <li>{0, 0, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 1, 97,
+ *                   98, 99, 100, 101, 102, 103, 104, 2, 1}
+ *               <li>version_id = 0;
+ *               <li>trace_id = {64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79}
+ *               <li>span_id = {97, 98, 99, 100, 101, 102, 103, 104};
+ *               <li>trace_options = {1};
+ *             </ul>
+ *       </ul>
+ * </ul>
+ */
+final class BinaryFormatImpl extends BinaryFormat {
+  private static final Tracestate TRACESTATE_DEFAULT = Tracestate.builder().build();
+  private static final byte VERSION_ID = 0;
+  private static final int VERSION_ID_OFFSET = 0;
+  // The version_id/field_id size in bytes.
+  private static final byte ID_SIZE = 1;
+  private static final byte TRACE_ID_FIELD_ID = 0;
+
+  // TODO: clarify if offsets are correct here. While the specification suggests you should stop
+  // parsing when you hit an unknown field, it does not suggest that fields must be declared in
+  // ID order. Rather it only groups by data type order, in this case Trace Context
+  // https://github.com/census-instrumentation/opencensus-specs/blob/master/encodings/BinaryEncoding.md#deserialization-rules
+  @VisibleForTesting static final int TRACE_ID_FIELD_ID_OFFSET = VERSION_ID_OFFSET + ID_SIZE;
+
+  private static final int TRACE_ID_OFFSET = TRACE_ID_FIELD_ID_OFFSET + ID_SIZE;
+  private static final byte SPAN_ID_FIELD_ID = 1;
+
+  @VisibleForTesting static final int SPAN_ID_FIELD_ID_OFFSET = TRACE_ID_OFFSET + TraceId.SIZE;
+
+  private static final int SPAN_ID_OFFSET = SPAN_ID_FIELD_ID_OFFSET + ID_SIZE;
+  private static final byte TRACE_OPTION_FIELD_ID = 2;
+
+  @VisibleForTesting static final int TRACE_OPTION_FIELD_ID_OFFSET = SPAN_ID_OFFSET + SpanId.SIZE;
+
+  private static final int TRACE_OPTIONS_OFFSET = TRACE_OPTION_FIELD_ID_OFFSET + ID_SIZE;
+  /** Version, Trace and Span IDs are required fields. */
+  private static final int REQUIRED_FORMAT_LENGTH = 3 * ID_SIZE + TraceId.SIZE + SpanId.SIZE;
+  /** Use {@link TraceOptions#DEFAULT} unless its optional field is present. */
+  private static final int ALL_FORMAT_LENGTH = REQUIRED_FORMAT_LENGTH + ID_SIZE + TraceOptions.SIZE;
+
+  @Override
+  public byte[] toByteArray(SpanContext spanContext) {
+    checkNotNull(spanContext, "spanContext");
+    byte[] bytes = new byte[ALL_FORMAT_LENGTH];
+    bytes[VERSION_ID_OFFSET] = VERSION_ID;
+    bytes[TRACE_ID_FIELD_ID_OFFSET] = TRACE_ID_FIELD_ID;
+    spanContext.getTraceId().copyBytesTo(bytes, TRACE_ID_OFFSET);
+    bytes[SPAN_ID_FIELD_ID_OFFSET] = SPAN_ID_FIELD_ID;
+    spanContext.getSpanId().copyBytesTo(bytes, SPAN_ID_OFFSET);
+    bytes[TRACE_OPTION_FIELD_ID_OFFSET] = TRACE_OPTION_FIELD_ID;
+    spanContext.getTraceOptions().copyBytesTo(bytes, TRACE_OPTIONS_OFFSET);
+    return bytes;
+  }
+
+  @Override
+  public SpanContext fromByteArray(byte[] bytes) throws SpanContextParseException {
+    checkNotNull(bytes, "bytes");
+    if (bytes.length == 0 || bytes[0] != VERSION_ID) {
+      throw new SpanContextParseException("Unsupported version.");
+    }
+    if (bytes.length < REQUIRED_FORMAT_LENGTH) {
+      throw new SpanContextParseException("Invalid input: truncated");
+    }
+    // TODO: the following logic assumes that fields are written in ID order. The spec does not say
+    // that. If it decides not to, this logic would need to be more like a loop
+    TraceId traceId;
+    SpanId spanId;
+    TraceOptions traceOptions = TraceOptions.DEFAULT;
+    int pos = 1;
+    if (bytes[pos] == TRACE_ID_FIELD_ID) {
+      traceId = TraceId.fromBytes(bytes, pos + ID_SIZE);
+      pos += ID_SIZE + TraceId.SIZE;
+    } else {
+      // TODO: update the spec to suggest that the trace ID is not actually optional
+      throw new SpanContextParseException("Invalid input: expected trace ID at offset " + pos);
+    }
+    if (bytes[pos] == SPAN_ID_FIELD_ID) {
+      spanId = SpanId.fromBytes(bytes, pos + ID_SIZE);
+      pos += ID_SIZE + SpanId.SIZE;
+    } else {
+      // TODO: update the spec to suggest that the span ID is not actually optional.
+      throw new SpanContextParseException("Invalid input: expected span ID at offset " + pos);
+    }
+    // Check to see if we are long enough to include an options field, and also that the next field
+    // is an options field. Per spec we simply stop parsing at first unknown field instead of
+    // failing.
+    if (bytes.length > pos && bytes[pos] == TRACE_OPTION_FIELD_ID) {
+      if (bytes.length < ALL_FORMAT_LENGTH) {
+        throw new SpanContextParseException("Invalid input: truncated");
+      }
+      traceOptions = TraceOptions.fromByte(bytes[pos + ID_SIZE]);
+    }
+    return SpanContext.create(traceId, spanId, traceOptions, TRACESTATE_DEFAULT);
+  }
+}
diff --git a/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/PropagationComponentImpl.java b/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/PropagationComponentImpl.java
new file mode 100644
index 00000000..f608543d
--- /dev/null
+++ b/impl_core/src/main/java/io/opencensus/implcore/trace/propagation/PropagationComponentImpl.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2017, OpenCensus 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.opencensus.implcore.trace.propagation;
+
+import io.opencensus.trace.propagation.BinaryFormat;
+import io.opencensus.trace.propagation.PropagationComponent;
+import io.opencensus.trace.propagation.TextFormat;
+
+/** Implementation of the {@link PropagationComponent}. */
+public class PropagationComponentImpl extends PropagationComponent {
+  private final BinaryFormat binaryFormat = new BinaryFormatImpl();
+  private final B3Format b3Format = new B3Format();
+
+  @Override
+  public BinaryFormat getBinaryFormat() {
+    return binaryFormat;
+  }
+
+  @Override
+  public TextFormat getB3Format() {
+    return b3Format;
+  }
+}