Tags: Add TagMetadata. (#1768)

Author: songy23

CHANGELOG.md

@@ -9,6 +9,7 @@
 - Add `metrics.data` package to hold common classes shared between stats and metrics.
 - Refactor `Exemplar` and `AttachmentValue` to be under `metrics.data`. Note that this is a breaking change
 if you're using the `Exemplar` classes or APIs in the previous releases.
+- Add `TagMetadata` that defines the properties associated with a `Tag`.
 
 # 0.19.0 - 2019-01-28
 - Add an artifact `opencensus-contrib-http-jetty-client` for instrumenting jetty http client. Add extractor for Jetty Client.

api/src/main/java/io/opencensus/tags/NoopTags.java

@@ -150,12 +150,21 @@ private static final class NoopTagContextBuilder extends TagContextBuilder {
     static final TagContextBuilder INSTANCE = new NoopTagContextBuilder();
 
     @Override
+    @SuppressWarnings("deprecation")
     public TagContextBuilder put(TagKey key, TagValue value) {
       Utils.checkNotNull(key, "key");
       Utils.checkNotNull(value, "value");
       return this;
     }
 
+    @Override
+    public TagContextBuilder put(TagKey key, TagValue value, TagMetadata tagMetadata) {
+      Utils.checkNotNull(key, "key");
+      Utils.checkNotNull(value, "value");
+      Utils.checkNotNull(tagMetadata, "tagMetadata");
+      return this;
+    }
+
     @Override
     public TagContextBuilder remove(TagKey key) {
       Utils.checkNotNull(key, "key");

api/src/main/java/io/opencensus/tags/Tag.java

@@ -17,6 +17,7 @@
 package io.opencensus.tags;
 
 import com.google.auto.value.AutoValue;
+import io.opencensus.tags.TagMetadata.TagTtl;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -28,18 +29,41 @@
 @AutoValue
 public abstract class Tag {
 
+  private static final TagMetadata METADATA_UNLIMITED_PROPAGATION =
+      TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION);
+
   Tag() {}
 
   /**
    * Creates a {@code Tag} from the given key and value.
    *
+   * <p>For backwards-compatibility this method still produces propagating {@link Tag}s.
+   *
+   * <p>This is equivalent to calling {@code create(key, value,
+   * TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION))}.
+   *
    * @param key the tag key.
    * @param value the tag value.
    * @return a {@code Tag} with the given key and value.
    * @since 0.8
+   * @deprecated in favor of {@link #create(TagKey, TagValue, TagMetadata)}.
    */
+  @Deprecated
   public static Tag create(TagKey key, TagValue value) {
-    return new AutoValue_Tag(key, value);
+    return create(key, value, METADATA_UNLIMITED_PROPAGATION);
+  }
+
+  /**
+   * Creates a {@code Tag} from the given key, value and metadata.
+   *
+   * @param key the tag key.
+   * @param value the tag value.
+   * @param tagMetadata the tag metadata.
+   * @return a {@code Tag}.
+   * @since 0.20
+   */
+  public static Tag create(TagKey key, TagValue value, TagMetadata tagMetadata) {
+    return new AutoValue_Tag(key, value, tagMetadata);
   }
 
   /**
@@ -57,4 +81,12 @@ public static Tag create(TagKey key, TagValue value) {
    * @since 0.8
    */
   public abstract TagValue getValue();
+
+  /**
+   * Returns the {@link TagMetadata} associated with this {@link Tag}.
+   *
+   * @return the {@code TagMetadata}.
+   * @since 0.20
+   */
+  public abstract TagMetadata getTagMetadata();
 }

api/src/main/java/io/opencensus/tags/TagContextBuilder.java

@@ -28,13 +28,31 @@ public abstract class TagContextBuilder {
   /**
    * Adds the key/value pair regardless of whether the key is present.
    *
+   * <p>For backwards-compatibility this method still produces propagating {@link Tag}s.
+   *
+   * <p>Equivalent to calling {@code put(key, value,
+   * TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION))}.
+   *
    * @param key the {@code TagKey} which will be set.
    * @param value the {@code TagValue} to set for the given key.
    * @return this
    * @since 0.8
+   * @deprecated in favor of {@link #put(TagKey, TagValue, TagMetadata)}.
    */
+  @Deprecated
   public abstract TagContextBuilder put(TagKey key, TagValue value);
 
+  /**
+   * Adds the key/value pair and metadata regardless of whether the key is present.
+   *
+   * @param key the {@code TagKey} which will be set.
+   * @param value the {@code TagValue} to set for the given key.
+   * @param tagMetadata the {@code TagMetadata} associated with this {@link Tag}.
+   * @return this
+   * @since 0.20
+   */
+  public abstract TagContextBuilder put(TagKey key, TagValue value, TagMetadata tagMetadata);
+
   /**
    * Removes the key if it exists.
    *

api/src/main/java/io/opencensus/tags/TagMetadata.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2019, 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.tags;
+
+import com.google.auto.value.AutoValue;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * {@link TagMetadata} contains properties associated with a {@link Tag}.
+ *
+ * <p>For now only the property {@link TagTtl} is defined. In future, additional properties may be
+ * added to address specific situations.
+ *
+ * @since 0.20
+ */
+@Immutable
+@AutoValue
+public abstract class TagMetadata {
+
+  TagMetadata() {}
+
+  /**
+   * Creates a {@link TagMetadata} with the given {@link TagTtl}.
+   *
+   * @param tagTtl TTL of a {@code Tag}.
+   * @return a {@code TagMetadata}.
+   * @since 0.20
+   */
+  public static TagMetadata create(TagTtl tagTtl) {
+    return new AutoValue_TagMetadata(tagTtl);
+  }
+
+  /**
+   * Returns the {@link TagTtl} of this {@link TagMetadata}.
+   *
+   * @return the {@code TagTtl}.
+   * @since 0.20
+   */
+  public abstract TagTtl getTagTtl();
+
+  /**
+   * {@link TagTtl} is an integer that represents number of hops a tag can propagate.
+   *
+   * <p>Anytime a sender serializes a tag, sends it over the wire and receiver deserializes the tag
+   * then the tag is considered to have travelled one hop.
+   *
+   * <p>There could be one or more proxy(ies) between sender and receiver. Proxies are treated as
+   * transparent entities and they are not counted as hops.
+   *
+   * <p>For now, only special values of {@link TagTtl} are supported.
+   *
+   * @since 0.20
+   */
+  public enum TagTtl {
+
+    /**
+     * A {@link Tag} with {@link TagTtl#NO_PROPAGATION} is considered to have local scope and is
+     * used within the process where it's created.
+     *
+     * @since 0.20
+     */
+    NO_PROPAGATION(0),
+
+    /**
+     * A {@link Tag} with {@link TagTtl#UNLIMITED_PROPAGATION} can propagate unlimited hops.
+     *
+     * <p>However, it is still subject to outgoing and incoming (on remote side) filter criteria.
+     *
+     * <p>{@link TagTtl#UNLIMITED_PROPAGATION} is typical used to track a request, which may be
+     * processed across multiple entities.
+     *
+     * @since 0.20
+     */
+    UNLIMITED_PROPAGATION(-1);
+
+    private final int hops;
+
+    private TagTtl(int hops) {
+      this.hops = hops;
+    }
+  }
+}

api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java

@@ -16,7 +16,10 @@
 
 package io.opencensus.tags.propagation;
 
+import io.opencensus.tags.Tag;
 import io.opencensus.tags.TagContext;
+import io.opencensus.tags.TagMetadata;
+import io.opencensus.tags.TagMetadata.TagTtl;
 
 /**
  * Object for serializing and deserializing {@link TagContext}s with the binary format.
@@ -34,6 +37,9 @@ public abstract class TagContextBinarySerializer {
    *
    * <p>This method should be the inverse of {@link #fromByteArray}.
    *
+   * <p>{@link Tag}s that have a {@link TagMetadata} with {@link TagTtl#NO_PROPAGATION} will not be
+   * serialized.
+   *
    * @param tags the {@code TagContext} to serialize.
    * @return the on-the-wire representation of a {@code TagContext}.
    * @throws TagContextSerializationException if the result would be larger than the maximum allowed

api/src/test/java/io/opencensus/tags/NoopTagsTest.java

@@ -134,6 +134,13 @@ public void noopTagContextBuilder_Put_DisallowsNullValue() {
     noopBuilder.put(KEY, null);
   }
 
+  @Test
+  public void noopTagContextBuilder_Put_DisallowsNullTagMetadata() {
+    TagContextBuilder noopBuilder = NoopTags.getNoopTagContextBuilder();
+    thrown.expect(NullPointerException.class);
+    noopBuilder.put(KEY, VALUE, null);
+  }
+
   @Test
   public void noopTagContextBuilder_Remove_DisallowsNullKey() {
     TagContextBuilder noopBuilder = NoopTags.getNoopTagContextBuilder();

api/src/test/java/io/opencensus/tags/TagMetadataTest.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2019, 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.tags;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.common.testing.EqualsTester;
+import io.opencensus.tags.TagMetadata.TagTtl;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for {@link TagMetadata}. */
+@RunWith(JUnit4.class)
+public class TagMetadataTest {
+
+  @Test
+  public void testGetTagTtl() {
+    TagMetadata tagMetadata = TagMetadata.create(TagTtl.NO_PROPAGATION);
+    assertThat(tagMetadata.getTagTtl()).isEqualTo(TagTtl.NO_PROPAGATION);
+  }
+
+  @Test
+  public void testEquals() {
+    new EqualsTester()
+        .addEqualityGroup(
+            TagMetadata.create(TagTtl.NO_PROPAGATION), TagMetadata.create(TagTtl.NO_PROPAGATION))
+        .addEqualityGroup(TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION))
+        .testEquals();
+  }
+}

api/src/test/java/io/opencensus/tags/TagTest.java

@@ -19,6 +19,7 @@
 import static com.google.common.truth.Truth.assertThat;
 
 import com.google.common.testing.EqualsTester;
+import io.opencensus.tags.TagMetadata.TagTtl;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
@@ -27,20 +28,41 @@
 @RunWith(JUnit4.class)
 public final class TagTest {
 
+  private static final TagKey KEY = TagKey.create("KEY");
+  private static final TagKey KEY_2 = TagKey.create("KEY2");
+  private static final TagValue VALUE = TagValue.create("VALUE");
+  private static final TagValue VALUE_2 = TagValue.create("VALUE2");
+  private static final TagMetadata METADATA_UNLIMITED_PROPAGATION =
+      TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION);
+  private static final TagMetadata METADATA_NO_PROPAGATION =
+      TagMetadata.create(TagTtl.NO_PROPAGATION);
+
   @Test
   public void testGetKey() {
-    assertThat(Tag.create(TagKey.create("k"), TagValue.create("v")).getKey())
-        .isEqualTo(TagKey.create("k"));
+    assertThat(Tag.create(KEY, VALUE).getKey()).isEqualTo(KEY);
+  }
+
+  @Test
+  public void testGetTagMetadata() {
+    assertThat(Tag.create(KEY, VALUE, METADATA_NO_PROPAGATION).getTagMetadata())
+        .isEqualTo(METADATA_NO_PROPAGATION);
+  }
+
+  @Test
+  public void testGetTagMetadata_default() {
+    assertThat(Tag.create(KEY, VALUE).getTagMetadata()).isEqualTo(METADATA_UNLIMITED_PROPAGATION);
   }
 
   @Test
   public void testTagEquals() {
     new EqualsTester()
         .addEqualityGroup(
-            Tag.create(TagKey.create("Key"), TagValue.create("foo")),
-            Tag.create(TagKey.create("Key"), TagValue.create("foo")))
-        .addEqualityGroup(Tag.create(TagKey.create("Key"), TagValue.create("bar")))
-        .addEqualityGroup(Tag.create(TagKey.create("Key2"), TagValue.create("foo")))
+            Tag.create(KEY, VALUE),
+            Tag.create(KEY, VALUE),
+            Tag.create(KEY, VALUE, METADATA_UNLIMITED_PROPAGATION))
+        .addEqualityGroup(Tag.create(KEY, VALUE_2))
+        .addEqualityGroup(Tag.create(KEY_2, VALUE))
+        .addEqualityGroup(Tag.create(KEY, VALUE, METADATA_NO_PROPAGATION))
         .testEquals();
   }
 }

contrib/http_util/src/main/java/io/opencensus/contrib/http/HttpClientHandler.java

@@ -17,6 +17,7 @@
 package io.opencensus.contrib.http;
 
 import static com.google.common.base.Preconditions.checkNotNull;
+import static io.opencensus.contrib.http.HttpRequestContext.METADATA_NO_PROPAGATION;
 import static io.opencensus.contrib.http.util.HttpMeasureConstants.HTTP_CLIENT_METHOD;
 import static io.opencensus.contrib.http.util.HttpMeasureConstants.HTTP_CLIENT_RECEIVED_BYTES;
 import static io.opencensus.contrib.http.util.HttpMeasureConstants.HTTP_CLIENT_ROUNDTRIP_LATENCY;
@@ -162,10 +163,14 @@ private void recordStats(
     TagContext startCtx =
         tagger
             .toBuilder(context.tagContext)
-            .put(HTTP_CLIENT_METHOD, TagValue.create(methodStr == null ? "" : methodStr))
+            .put(
+                HTTP_CLIENT_METHOD,
+                TagValue.create(methodStr == null ? "" : methodStr),
+                METADATA_NO_PROPAGATION)
             .put(
                 HTTP_CLIENT_STATUS,
-                TagValue.create(status == 0 ? "error" : Integer.toString(status)))
+                TagValue.create(status == 0 ? "error" : Integer.toString(status)),
+                METADATA_NO_PROPAGATION)
             .build();
 
     statsRecorder