Tags: Add TagContextBuilder.putPropagating(). (#1852)

Author: songy23

CHANGELOG.md

@@ -4,7 +4,8 @@
 - Add an option to allow users to override the default "opencensus_task" metric label in Stackdriver Stats Exporter.
 - Allow setting custom namespace in Prometheus exporter.
 - Add Cumulative (`DoubleCumulative`, `LongCumulative`, `DerivedDoubleCumulative`, `DerivedLongCumulative`) APIs.
-- Add a convenient API `TagContextBuilder.putLocal()` that adds non-propagating tags.
+- Add convenience APIs `TagContextBuilder.putLocal()` that adds non-propagating tags,
+and `TagContextBuilder.putPropagating()` that adds unlimited propagating tags.
 
 ## 0.20.0 - 2019-03-28
 - Add OpenCensus Java OC-Agent Trace Exporter.

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

@@ -28,6 +28,8 @@ public abstract class TagContextBuilder {
 
   private static final TagMetadata METADATA_NO_PROPAGATION =
       TagMetadata.create(TagTtl.NO_PROPAGATION);
+  private static final TagMetadata METADATA_UNLIMITED_PROPAGATION =
+      TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION);
 
   /**
    * Adds the key/value pair regardless of whether the key is present.
@@ -77,6 +79,25 @@ public final TagContextBuilder putLocal(TagKey key, TagValue value) {
     return put(key, value, METADATA_NO_PROPAGATION);
   }
 
+  /**
+   * Adds an unlimited propagating tag to this {@code TagContextBuilder}.
+   *
+   * <p>This is equivalent to calling {@code put(key, value,
+   * TagMetadata.create(TagTtl.METADATA_UNLIMITED_PROPAGATION))}.
+   *
+   * <p>Only call this method if you want propagating tags. If you want tags for breaking down
+   * metrics, or there are sensitive messages in your tags, use {@link #putLocal(TagKey, TagValue)}
+   * instead.
+   *
+   * @param key the {@code TagKey} which will be set.
+   * @param value the {@code TagValue} to set for the given key.
+   * @return this
+   * @since 0.21
+   */
+  public final TagContextBuilder putPropagating(TagKey key, TagValue value) {
+    return put(key, value, METADATA_UNLIMITED_PROPAGATION);
+  }
+
   /**
    * Removes the key if it exists.
    *

impl_core/src/test/java/io/opencensus/implcore/tags/TagMapImplTest.java

@@ -120,6 +120,13 @@ public void putLocal() {
     assertThat(tags1).isEqualTo(tags2);
   }
 
+  @Test
+  public void putPropagating() {
+    TagContext tags1 = tagger.emptyBuilder().put(K1, V1, METADATA_UNLIMITED_PROPAGATION).build();
+    TagContext tags2 = tagger.emptyBuilder().putPropagating(K1, V1).build();
+    assertThat(tags1).isEqualTo(tags2);
+  }
+
   @Test
   public void remove_existingKey() {
     TagContext tags = new TagMapImpl(ImmutableMap.of(K1, VM1, K2, VM2));