Stats: Add API MeasureMap.putAttachment() for recording exemplars. (#1285)

* Stats: Add API MeasureMap.withAttachments() for recording exemplars.

* Add this change to CHANGELOG

* Stats: implement the new API in impl.

* Rename API and merge the string maps on multiple calls.

* Update the API to putAttachment(String, String) for simplicity.

* Fix a typo and add a TODO about making putAttachment abstract.

2 files changed, 37 insertions, 0 deletions

diff --git a/api/src/main/java/io/opencensus/stats/MeasureMap.java b/api/src/main/java/io/opencensus/stats/MeasureMap.java
index a7430537..beb84f06 100644
--- a/api/src/main/java/io/opencensus/stats/MeasureMap.java
+++ b/api/src/main/java/io/opencensus/stats/MeasureMap.java
@@ -16,6 +16,7 @@
 
 package io.opencensus.stats;
 
+import io.opencensus.internal.Utils;
 import io.opencensus.stats.Measure.MeasureDouble;
 import io.opencensus.stats.Measure.MeasureLong;
 import io.opencensus.tags.TagContext;
@@ -52,6 +53,25 @@ public abstract class MeasureMap {
   public abstract MeasureMap put(MeasureLong measure, long value);
 
   /**
+   * Associate the contextual information of an {@code Exemplar} to this {@link MeasureMap}.
+   * Contextual information is represented as {@code String} key-value pairs.
+   *
+   * <p>If this method is called multiple times with the same key, only the last value will be kept.
+   *
+   * @param key the key of contextual information of an {@code Exemplar}.
+   * @param value the string representation of contextual information of an {@code Exemplar}.
+   * @return this
+   * @since 0.16
+   */
+  // TODO(songya): make this method abstract in the 0.17 release.
+  public MeasureMap putAttachment(String key, String value) {
+    // Provides a default no-op implementation to avoid breaking other existing sub-classes.
+    Utils.checkNotNull(key, "key");
+    Utils.checkNotNull(value, "value");
+    return this;
+  }
+
+  /**
    * Records all of the measures at the same time, with the current {@link TagContext}.
    *
    * <p>This method records all of the stats in the {@code MeasureMap} every time it is called.
diff --git a/api/src/test/java/io/opencensus/stats/NoopStatsTest.java b/api/src/test/java/io/opencensus/stats/NoopStatsTest.java
index b3f81715..4bae14a6 100644
--- a/api/src/test/java/io/opencensus/stats/NoopStatsTest.java
+++ b/api/src/test/java/io/opencensus/stats/NoopStatsTest.java
@@ -93,6 +93,22 @@ public final class NoopStatsTest {
     noopStatsComponent.setState(StatsCollectionState.ENABLED);
   }
 
+  @Test
+  public void noopStatsRecorder_PutAttachmentNullKey() {
+    MeasureMap measureMap = NoopStats.getNoopStatsRecorder().newMeasureMap();
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("key");
+    measureMap.putAttachment(null, "value");
+  }
+
+  @Test
+  public void noopStatsRecorder_PutAttachmentNullValue() {
+    MeasureMap measureMap = NoopStats.getNoopStatsRecorder().newMeasureMap();
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("value");
+    measureMap.putAttachment("key", null);
+  }
+
   // The NoopStatsRecorder should do nothing, so this test just checks that record doesn't throw an
   // exception.
   @Test
@@ -111,6 +127,7 @@ public final class NoopStatsTest {
   public void noopStatsRecorder_Record_DisallowNullTagContext() {
     MeasureMap measureMap = NoopStats.getNoopStatsRecorder().newMeasureMap();
     thrown.expect(NullPointerException.class);
+    thrown.expectMessage("tags");
     measureMap.record(null);
   }
 }