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.

4 files changed, 73 insertions, 13 deletions

diff --git a/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureMapImpl.java b/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureMapImpl.java
index a156747f..ee51796c 100644
--- a/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureMapImpl.java
+++ b/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureMapImpl.java
@@ -48,6 +48,12 @@ final class MeasureMapImpl extends MeasureMap {
   }
 
   @Override
+  public MeasureMap putAttachment(String key, String value) {
+    builder.putAttachment(key, value);
+    return this;
+  }
+
+  @Override
   public void record() {
     // Use the context key directly, to avoid depending on the tags implementation.
     record(ContextUtils.TAG_CONTEXT_KEY.get());
diff --git a/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureMapInternal.java b/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureMapInternal.java
index c68b4aff..304ff8c4 100644
--- a/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureMapInternal.java
+++ b/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureMapInternal.java
@@ -21,8 +21,12 @@ import io.opencensus.stats.Measure.MeasureDouble;
 import io.opencensus.stats.Measure.MeasureLong;
 import io.opencensus.stats.Measurement;
 import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
 import java.util.Iterator;
+import java.util.Map;
 import java.util.NoSuchElementException;
+import javax.annotation.Nullable;
 
 // TODO(songya): consider combining MeasureMapImpl and this class.
 /** A map from {@link Measure}'s to measured values. */
@@ -41,10 +45,21 @@ final class MeasureMapInternal {
     return new MeasureMapInternalIterator();
   }
 
+  // Returns the contextual information associated with an example value.
+  Map<String, String> getAttachments() {
+    return attachments;
+  }
+
   private final ArrayList<Measurement> measurements;
+  @Nullable private final Map<String, String> attachments;
 
-  private MeasureMapInternal(ArrayList<Measurement> measurements) {
+  private MeasureMapInternal(
+      ArrayList<Measurement> measurements, @Nullable Map<String, String> attachments) {
     this.measurements = measurements;
+    this.attachments =
+        attachments == null
+            ? null
+            : Collections.unmodifiableMap(new HashMap<String, String>(attachments));
   }
 
   /** Builder for the {@link MeasureMapInternal} class. */
@@ -75,6 +90,14 @@ final class MeasureMapInternal {
       return this;
     }
 
+    Builder putAttachment(String key, String value) {
+      if (this.attachments == null) {
+        this.attachments = new HashMap<String, String>();
+      }
+      this.attachments.put(key, value);
+      return this;
+    }
+
     /** Constructs a {@link MeasureMapInternal} from the current measurements. */
     MeasureMapInternal build() {
       // Note: this makes adding measurements quadratic but is fastest for the sizes of
@@ -88,10 +111,11 @@ final class MeasureMapInternal {
           }
         }
       }
-      return new MeasureMapInternal(measurements);
+      return new MeasureMapInternal(measurements, attachments);
     }
 
     private final ArrayList<Measurement> measurements = new ArrayList<Measurement>();
+    @Nullable private Map<String, String> attachments;
 
     private Builder() {}
   }
diff --git a/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureToViewMap.java b/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureToViewMap.java
index 34341bad..58d41c0d 100644
--- a/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureToViewMap.java
+++ b/impl_core/src/main/java/io/opencensus/implcore/stats/MeasureToViewMap.java
@@ -146,6 +146,7 @@ final class MeasureToViewMap {
   // Records stats with a set of tags.
   synchronized void record(TagContext tags, MeasureMapInternal stats, Timestamp timestamp) {
     Iterator<Measurement> iterator = stats.iterator();
+    Map<String, String> attachments = stats.getAttachments();
     while (iterator.hasNext()) {
       Measurement measurement = iterator.next();
       Measure measure = measurement.getMeasure();
@@ -156,8 +157,8 @@ final class MeasureToViewMap {
       Collection<MutableViewData> views = mutableMap.get(measure.getName());
       for (MutableViewData view : views) {
         measurement.match(
-            new RecordDoubleValueFunc(tags, view, timestamp),
-            new RecordLongValueFunc(tags, view, timestamp),
+            new RecordDoubleValueFunc(tags, view, timestamp, attachments),
+            new RecordLongValueFunc(tags, view, timestamp, attachments),
             Functions.</*@Nullable*/ Void>throwAssertionError());
       }
     }
@@ -184,36 +185,48 @@ final class MeasureToViewMap {
   private static final class RecordDoubleValueFunc implements Function<MeasurementDouble, Void> {
     @Override
     public Void apply(MeasurementDouble arg) {
-      view.record(tags, arg.getValue(), timestamp);
+      view.record(tags, arg.getValue(), timestamp, attachments);
       return null;
     }
 
     private final TagContext tags;
     private final MutableViewData view;
     private final Timestamp timestamp;
+    @javax.annotation.Nullable private final Map<String, String> attachments;
 
-    private RecordDoubleValueFunc(TagContext tags, MutableViewData view, Timestamp timestamp) {
+    private RecordDoubleValueFunc(
+        TagContext tags,
+        MutableViewData view,
+        Timestamp timestamp,
+        @javax.annotation.Nullable Map<String, String> attachments) {
       this.tags = tags;
       this.view = view;
       this.timestamp = timestamp;
+      this.attachments = attachments;
     }
   }
 
   private static final class RecordLongValueFunc implements Function<MeasurementLong, Void> {
     @Override
     public Void apply(MeasurementLong arg) {
-      view.record(tags, arg.getValue(), timestamp);
+      view.record(tags, arg.getValue(), timestamp, attachments);
       return null;
     }
 
     private final TagContext tags;
     private final MutableViewData view;
     private final Timestamp timestamp;
+    @javax.annotation.Nullable private final Map<String, String> attachments;
 
-    private RecordLongValueFunc(TagContext tags, MutableViewData view, Timestamp timestamp) {
+    private RecordLongValueFunc(
+        TagContext tags,
+        MutableViewData view,
+        Timestamp timestamp,
+        @javax.annotation.Nullable Map<String, String> attachments) {
       this.tags = tags;
       this.view = view;
       this.timestamp = timestamp;
+      this.attachments = attachments;
     }
   }
 }
diff --git a/impl_core/src/main/java/io/opencensus/implcore/stats/MutableViewData.java b/impl_core/src/main/java/io/opencensus/implcore/stats/MutableViewData.java
index 8e527dc6..932da745 100644
--- a/impl_core/src/main/java/io/opencensus/implcore/stats/MutableViewData.java
+++ b/impl_core/src/main/java/io/opencensus/implcore/stats/MutableViewData.java
@@ -101,12 +101,21 @@ abstract class MutableViewData {
   }
 
   /** Record double stats with the given tags. */
-  abstract void record(TagContext context, double value, Timestamp timestamp);
+  // TODO(songya): store the attachments in MutableDistribution.
+  abstract void record(
+      TagContext context,
+      double value,
+      Timestamp timestamp,
+      @javax.annotation.Nullable Map<String, String> attachments);
 
   /** Record long stats with the given tags. */
-  void record(TagContext tags, long value, Timestamp timestamp) {
+  void record(
+      TagContext tags,
+      long value,
+      Timestamp timestamp,
+      @javax.annotation.Nullable Map<String, String> attachments) {
     // TODO(songya): shall we check for precision loss here?
-    record(tags, (double) value, timestamp);
+    record(tags, (double) value, timestamp, attachments);
   }
 
   /** Convert this {@link MutableViewData} to {@link ViewData}. */
@@ -206,7 +215,11 @@ abstract class MutableViewData {
     }
 
     @Override
-    void record(TagContext context, double value, Timestamp timestamp) {
+    void record(
+        TagContext context,
+        double value,
+        Timestamp timestamp,
+        @javax.annotation.Nullable Map<String, String> attachments) {
       List</*@Nullable*/ TagValue> tagValues =
           getTagValues(getTagMap(context), super.view.getColumns());
       if (!tagValueAggregationMap.containsKey(tagValues)) {
@@ -300,7 +313,11 @@ abstract class MutableViewData {
     }
 
     @Override
-    void record(TagContext context, double value, Timestamp timestamp) {
+    void record(
+        TagContext context,
+        double value,
+        Timestamp timestamp,
+        @javax.annotation.Nullable Map<String, String> attachments) {
       List</*@Nullable*/ TagValue> tagValues =
           getTagValues(getTagMap(context), super.view.getColumns());
       refreshBucketList(timestamp);