Tags: Add TagContextBuilder.putLocal(). (#1851)

Author: songy23

CHANGELOG.md

@@ -4,6 +4,7 @@
 - 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.
 
 ## 0.20.0 - 2019-03-28
 - Add OpenCensus Java OC-Agent Trace Exporter.

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

@@ -17,13 +17,18 @@
 package io.opencensus.tags;
 
 import io.opencensus.common.Scope;
+import io.opencensus.tags.TagMetadata.TagTtl;
 
 /**
  * Builder for the {@link TagContext} class.
  *
  * @since 0.8
  */
 public abstract class TagContextBuilder {
+
+  private static final TagMetadata METADATA_NO_PROPAGATION =
+      TagMetadata.create(TagTtl.NO_PROPAGATION);
+
   /**
    * Adds the key/value pair regardless of whether the key is present.
    *
@@ -36,7 +41,8 @@ public abstract class TagContextBuilder {
    * @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 in favor of {@link #put(TagKey, TagValue, TagMetadata)}, or {@link
+   *     #putLocal(TagKey, TagValue)} if you only want in-process tags.
    */
   @Deprecated
   public abstract TagContextBuilder put(TagKey key, TagValue value);
@@ -56,6 +62,21 @@ public TagContextBuilder put(TagKey key, TagValue value, TagMetadata tagMetadata
     return builder;
   }
 
+  /**
+   * Adds a non-propagating tag to this {@code TagContextBuilder}.
+   *
+   * <p>This is equivalent to calling {@code put(key, value,
+   * TagMetadata.create(TagTtl.NO_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.21
+   */
+  public final TagContextBuilder putLocal(TagKey key, TagValue value) {
+    return put(key, value, METADATA_NO_PROPAGATION);
+  }
+
   /**
    * Removes the key if it exists.
    *

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

@@ -53,6 +53,8 @@ public class TagMapImplTest {
 
   private static final TagMetadata METADATA_UNLIMITED_PROPAGATION =
       TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION);
+  private static final TagMetadata METADATA_NO_PROPAGATION =
+      TagMetadata.create(TagTtl.NO_PROPAGATION);
 
   private static final TagKey K1 = TagKey.create("k1");
   private static final TagKey K2 = TagKey.create("k2");
@@ -111,6 +113,13 @@ public void put_nullValue() {
     builder.put(K2, null);
   }
 
+  @Test
+  public void putLocal() {
+    TagContext tags1 = tagger.emptyBuilder().put(K1, V1, METADATA_NO_PROPAGATION).build();
+    TagContext tags2 = tagger.emptyBuilder().putLocal(K1, V1).build();
+    assertThat(tags1).isEqualTo(tags2);
+  }
+
   @Test
   public void remove_existingKey() {
     TagContext tags = new TagMapImpl(ImmutableMap.of(K1, VM1, K2, VM2));