Exemplar: Refactor to be under metrics.data. (#1791)

* Exemplar: Refactor to be under common.

* Update all impl and contrib.

* Move Exemplar and AttachmentValue to metrics.data.

* Add a note in CHANGELOG.

Author: songy23

CHANGELOG.md

@@ -6,6 +6,9 @@
 - Modified default value to false for publicEndpoint property in Http-Servlet.
 - Add a generic `AttachmentValue` class to support `Exemplar`.
 - Add Elasticsearch Trace Exporter.
+- 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.
 
 # 0.19.0 - 2019-01-28
 - Add an artifact `opencensus-contrib-http-jetty-client` for instrumenting jetty http client. Add extractor for Jetty Client.

…io/opencensus/stats/AttachmentValue.java …census/metrics/data/AttachmentValue.javaapi/src/main/java/io/opencensus/stats/AttachmentValue.java renamed to api/src/main/java/io/opencensus/metrics/data/AttachmentValue.java api/src/main/java/io/opencensus/stats/AttachmentValue.java renamed to api/src/main/java/io/opencensus/metrics/data/AttachmentValue.java

@@ -14,10 +14,9 @@
  * limitations under the License.
  */
 
-package io.opencensus.stats;
+package io.opencensus.metrics.data;
 
 import com.google.auto.value.AutoValue;
-import io.opencensus.stats.AggregationData.DistributionData.Exemplar;
 import javax.annotation.concurrent.Immutable;
 
 /**

api/src/main/java/io/opencensus/metrics/data/Exemplar.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.metrics.data;
+
+import com.google.auto.value.AutoValue;
+import io.opencensus.common.Timestamp;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Map.Entry;
+import javax.annotation.concurrent.Immutable;
+
+/*>>>
+import org.checkerframework.checker.nullness.qual.NonNull;
+*/
+
+/**
+ * An example point that may be used to annotate aggregated distribution values, associated with a
+ * histogram bucket.
+ *
+ * @since 0.20
+ */
+@Immutable
+@AutoValue
+public abstract class Exemplar {
+
+  Exemplar() {}
+
+  /**
+   * Returns value of the {@link Exemplar} point.
+   *
+   * @return value of the {@code Exemplar} point.
+   * @since 0.20
+   */
+  public abstract double getValue();
+
+  /**
+   * Returns the time that this {@link Exemplar}'s value was recorded.
+   *
+   * @return the time that this {@code Exemplar}'s value was recorded.
+   * @since 0.20
+   */
+  public abstract Timestamp getTimestamp();
+
+  /**
+   * Returns the contextual information about the example value.
+   *
+   * @return the contextual information about the example value.
+   * @since 0.20
+   */
+  public abstract Map<String, AttachmentValue> getAttachments();
+
+  /**
+   * Creates an {@link Exemplar}.
+   *
+   * @param value value of the {@link Exemplar} point.
+   * @param timestamp the time that this {@code Exemplar}'s value was recorded.
+   * @param attachments the contextual information about the example value.
+   * @return an {@code Exemplar}.
+   * @since 0.20
+   */
+  public static Exemplar create(
+      double value, Timestamp timestamp, Map<String, AttachmentValue> attachments) {
+    checkNotNull(attachments, "attachments");
+    Map<String, AttachmentValue> attachmentsCopy =
+        Collections.unmodifiableMap(new HashMap<String, AttachmentValue>(attachments));
+    for (Entry<String, AttachmentValue> entry : attachmentsCopy.entrySet()) {
+      checkNotNull(entry.getKey(), "key of attachments");
+      checkNotNull(entry.getValue(), "value of attachments");
+    }
+    return new AutoValue_Exemplar(value, timestamp, attachmentsCopy);
+  }
+
+  // TODO(songy23): shade the internal Utils jar and remove this duplicated method.
+  private static <T /*>>> extends @NonNull Object*/> T checkNotNull(
+      T arg, @javax.annotation.Nullable Object errorMessage) {
+    if (arg == null) {
+      throw new NullPointerException(String.valueOf(errorMessage));
+    }
+    return arg;
+  }
+}

api/src/main/java/io/opencensus/metrics/export/Distribution.java

@@ -19,14 +19,11 @@
 import com.google.auto.value.AutoValue;
 import io.opencensus.common.ExperimentalApi;
 import io.opencensus.common.Function;
-import io.opencensus.common.Timestamp;
 import io.opencensus.internal.Utils;
+import io.opencensus.metrics.data.Exemplar;
 import java.util.ArrayList;
 import java.util.Collections;
-import java.util.HashMap;
 import java.util.List;
-import java.util.Map;
-import java.util.Map.Entry;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
@@ -284,62 +281,4 @@ public static Bucket create(long count, Exemplar exemplar) {
     @Nullable
     public abstract Exemplar getExemplar();
   }
-
-  /**
-   * An example point that may be used to annotate aggregated distribution values, associated with a
-   * histogram bucket.
-   *
-   * @since 0.17
-   */
-  @Immutable
-  @AutoValue
-  public abstract static class Exemplar {
-
-    Exemplar() {}
-
-    /**
-     * Returns value of the {@link Exemplar} point.
-     *
-     * @return value of the {@code Exemplar} point.
-     * @since 0.17
-     */
-    public abstract double getValue();
-
-    /**
-     * Returns the time that this {@link Exemplar}'s value was recorded.
-     *
-     * @return the time that this {@code Exemplar}'s value was recorded.
-     * @since 0.17
-     */
-    public abstract Timestamp getTimestamp();
-
-    /**
-     * Returns the contextual information about the example value, represented as a string map.
-     *
-     * @return the contextual information about the example value.
-     * @since 0.17
-     */
-    public abstract Map<String, String> getAttachments();
-
-    /**
-     * Creates an {@link Exemplar}.
-     *
-     * @param value value of the {@link Exemplar} point.
-     * @param timestamp the time that this {@code Exemplar}'s value was recorded.
-     * @param attachments the contextual information about the example value.
-     * @return an {@code Exemplar}.
-     * @since 0.17
-     */
-    public static Exemplar create(
-        double value, Timestamp timestamp, Map<String, String> attachments) {
-      Utils.checkNotNull(attachments, "attachments");
-      Map<String, String> attachmentsCopy =
-          Collections.unmodifiableMap(new HashMap<String, String>(attachments));
-      for (Entry<String, String> entry : attachmentsCopy.entrySet()) {
-        Utils.checkNotNull(entry.getKey(), "key of attachments");
-        Utils.checkNotNull(entry.getValue(), "value of attachments");
-      }
-      return new AutoValue_Distribution_Exemplar(value, timestamp, attachmentsCopy);
-    }
-  }
 }

api/src/main/java/io/opencensus/stats/AggregationData.java

@@ -18,14 +18,11 @@
 
 import com.google.auto.value.AutoValue;
 import io.opencensus.common.Function;
-import io.opencensus.common.Timestamp;
 import io.opencensus.internal.Utils;
+import io.opencensus.metrics.data.Exemplar;
 import java.util.ArrayList;
 import java.util.Collections;
-import java.util.HashMap;
 import java.util.List;
-import java.util.Map;
-import java.util.Map.Entry;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -445,65 +442,6 @@ public final <T> T match(
         Function<? super AggregationData, T> defaultFunction) {
       return p3.apply(this);
     }
-
-    /**
-     * An example point that may be used to annotate aggregated distribution values, associated with
-     * a histogram bucket.
-     *
-     * @since 0.16
-     */
-    @Immutable
-    @AutoValue
-    public abstract static class Exemplar {
-
-      Exemplar() {}
-
-      /**
-       * Returns value of the {@link Exemplar} point.
-       *
-       * @return value of the {@code Exemplar} point.
-       * @since 0.16
-       */
-      public abstract double getValue();
-
-      /**
-       * Returns the time that this {@link Exemplar}'s value was recorded.
-       *
-       * @return the time that this {@code Exemplar}'s value was recorded.
-       * @since 0.16
-       */
-      public abstract Timestamp getTimestamp();
-
-      /**
-       * Returns the contextual information about the example value.
-       *
-       * @return the contextual information about the example value.
-       * @since 0.20
-       */
-      public abstract Map<String, AttachmentValue> getAttachments();
-
-      /**
-       * Creates an {@link Exemplar}.
-       *
-       * @param value value of the {@link Exemplar} point.
-       * @param timestamp the time that this {@code Exemplar}'s value was recorded.
-       * @param attachments the contextual information about the example value.
-       * @return an {@code Exemplar}.
-       * @since 0.20
-       */
-      public static Exemplar create(
-          double value, Timestamp timestamp, Map<String, AttachmentValue> attachments) {
-        Utils.checkNotNull(attachments, "attachments");
-        Map<String, AttachmentValue> attachmentsCopy =
-            Collections.unmodifiableMap(new HashMap<String, AttachmentValue>(attachments));
-        for (Entry<String, AttachmentValue> entry : attachmentsCopy.entrySet()) {
-          Utils.checkNotNull(entry.getKey(), "key of attachments");
-          Utils.checkNotNull(entry.getValue(), "value of attachments");
-        }
-        return new AutoValue_AggregationData_DistributionData_Exemplar(
-            value, timestamp, attachmentsCopy);
-      }
-    }
   }
 
   /**

api/src/main/java/io/opencensus/stats/MeasureMap.java

@@ -17,7 +17,8 @@
 package io.opencensus.stats;
 
 import io.opencensus.internal.Utils;
-import io.opencensus.stats.AttachmentValue.AttachmentValueString;
+import io.opencensus.metrics.data.AttachmentValue;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
 import io.opencensus.stats.Measure.MeasureDouble;
 import io.opencensus.stats.Measure.MeasureLong;
 import io.opencensus.tags.TagContext;

…pencensus/stats/AttachmentValueTest.java …us/metrics/data/AttachmentValueTest.javaapi/src/test/java/io/opencensus/stats/AttachmentValueTest.java renamed to api/src/test/java/io/opencensus/metrics/data/AttachmentValueTest.java api/src/test/java/io/opencensus/stats/AttachmentValueTest.java renamed to api/src/test/java/io/opencensus/metrics/data/AttachmentValueTest.java

@@ -14,18 +14,18 @@
  * limitations under the License.
  */
 
-package io.opencensus.stats;
+package io.opencensus.metrics.data;
 
 import static com.google.common.truth.Truth.assertThat;
 
-import io.opencensus.stats.AttachmentValue.AttachmentValueString;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
 
-/** Unit tests for {@link AttachmentValue}. */
+/** Unit tests for {@link io.opencensus.metrics.data.AttachmentValue}. */
 @RunWith(JUnit4.class)
 public class AttachmentValueTest {
 

api/src/test/java/io/opencensus/metrics/data/ExemplarTest.java

@@ -0,0 +1,79 @@
+/*
+ * 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.metrics.data;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import io.opencensus.common.Timestamp;
+import io.opencensus.metrics.data.AttachmentValue.AttachmentValueString;
+import java.util.Collections;
+import java.util.Map;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.ExpectedException;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link io.opencensus.metrics.data.Exemplar}. */
+@RunWith(JUnit4.class)
+public class ExemplarTest {
+
+  private static final double TOLERANCE = 1e-6;
+  private static final Timestamp TIMESTAMP_1 = Timestamp.create(1, 0);
+  private static final AttachmentValue ATTACHMENT_VALUE = AttachmentValueString.create("value");
+  private static final Map<String, AttachmentValue> ATTACHMENTS =
+      Collections.singletonMap("key", ATTACHMENT_VALUE);
+
+  @Rule public ExpectedException thrown = ExpectedException.none();
+
+  @Test
+  public void testExemplar() {
+    Exemplar exemplar = Exemplar.create(15.0, TIMESTAMP_1, ATTACHMENTS);
+    assertThat(exemplar.getValue()).isWithin(TOLERANCE).of(15.0);
+    assertThat(exemplar.getTimestamp()).isEqualTo(TIMESTAMP_1);
+    assertThat(exemplar.getAttachments()).isEqualTo(ATTACHMENTS);
+  }
+
+  @Test
+  public void testExemplar_PreventNullTimestamp() {
+    thrown.expect(NullPointerException.class);
+    Exemplar.create(15, null, ATTACHMENTS);
+  }
+
+  @Test
+  public void testExemplar_PreventNullAttachments() {
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("attachments");
+    Exemplar.create(15, TIMESTAMP_1, null);
+  }
+
+  @Test
+  public void testExemplar_PreventNullAttachmentKey() {
+    Map<String, AttachmentValue> attachments = Collections.singletonMap(null, ATTACHMENT_VALUE);
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("key of attachment");
+    Exemplar.create(15, TIMESTAMP_1, attachments);
+  }
+
+  @Test
+  public void testExemplar_PreventNullAttachmentValue() {
+    Map<String, AttachmentValue> attachments = Collections.singletonMap("key", null);
+    thrown.expect(NullPointerException.class);
+    thrown.expectMessage("value of attachment");
+    Exemplar.create(15, TIMESTAMP_1, attachments);
+  }
+}