Rename Timeseries with Handle. (#508)

api/src/main/java/io/opentelemetry/metrics/CounterDouble.java

@@ -16,6 +16,7 @@
 
 package io.opentelemetry.metrics;
 
+import io.opentelemetry.metrics.CounterDouble.Handle;
 import java.util.List;
 import javax.annotation.concurrent.ThreadSafe;
 
@@ -36,20 +37,20 @@ import javax.annotation.concurrent.ThreadSafe;
  *           .setUnit("1")
  *           .setLabelKeys(Collections.singletonList("Key"))
  *           .build();
- *   // It is recommended to keep a reference of a TimeSeries.
+ *   // It is recommended to keep a reference of a Handle.
- *   private static final CounterDouble.TimeSeries inboundTimeSeries =
+ *   private static final CounterDouble.Handle inboundHandle =
- *       counter.getOrCreateTimeSeries(Collections.singletonList("SomeWork"));
+ *       counter.getHandle(Collections.singletonList("SomeWork"));
- *   private static final CounterDouble.TimeSeries defaultTimeSeries =
+ *   private static final CounterDouble.Handle defaultHandle =
- *       counter.getDefaultTimeSeries();
+ *       counter.getDefaultHandle();
  *
  *   void doDefaultWork() {
  *      // Your code here.
- *      defaultTimeSeries.add(10);
+ *      defaultHandle.add(10);
  *   }
  *
  *   void doSomeWork() {
  *      // Your code here.
- *      inboundTimeSeries.set(15);
+ *      inboundHandle.set(15);
  *   }
  *
  * }
@@ -58,20 +59,20 @@ import javax.annotation.concurrent.ThreadSafe;
  * @since 0.1.0
  */
 @ThreadSafe
-public interface CounterDouble extends Metric<CounterDouble.TimeSeries> {
+public interface CounterDouble extends Metric<Handle> {
 
   @Override
-  TimeSeries getOrCreateTimeSeries(List<String> labelValues);
+  Handle getHandle(List<String> labelValues);
 
   @Override
-  TimeSeries getDefaultTimeSeries();
+  Handle getDefaultHandle();
 
   /**
-   * A {@code TimeSeries} for a {@code CounterDouble}.
+   * A {@code Handle} for a {@code CounterDouble}.
    *
    * @since 0.1.0
    */
-  interface TimeSeries {
+  interface Handle {
 
     /**
      * Adds the given value to the current value. The values cannot be negative.

api/src/main/java/io/opentelemetry/metrics/CounterLong.java

@@ -16,7 +16,7 @@
 
 package io.opentelemetry.metrics;
 
-import io.opentelemetry.metrics.CounterLong.TimeSeries;
+import io.opentelemetry.metrics.CounterLong.Handle;
 import java.util.List;
 import javax.annotation.concurrent.ThreadSafe;
 
@@ -37,19 +37,19 @@ import javax.annotation.concurrent.ThreadSafe;
  *           .setUnit("1")
  *           .setLabelKeys(Collections.singletonList("Key"))
  *           .build();
- *   // It is recommended to keep a reference of a TimeSeries.
+ *   // It is recommended to keep a reference of a Handle.
- *   private static final CounterLong.TimeSeries inboundTimeSeries =
+ *   private static final CounterLong.Handle inboundHandle =
- *       counter.getOrCreateTimeSeries(Collections.singletonList("SomeWork"));
+ *       counter.getHandle(Collections.singletonList("SomeWork"));
- *   private static final CounterLong.TimeSeries defaultTimeSeries = counter.getDefaultTimeSeries();
+ *   private static final CounterLong.Handle defaultHandle = counter.getDefaultHandle();
  *
  *   void doDefaultWork() {
  *      // Your code here.
- *      defaultTimeSeries.add(10);
+ *      defaultHandle.add(10);
  *   }
  *
  *   void doSomeWork() {
  *      // Your code here.
- *      inboundTimeSeries.set(15);
+ *      inboundHandle.set(15);
  *   }
  *
  * }
@@ -58,20 +58,20 @@ import javax.annotation.concurrent.ThreadSafe;
  * @since 0.1.0
  */
 @ThreadSafe
-public interface CounterLong extends Metric<TimeSeries> {
+public interface CounterLong extends Metric<Handle> {
 
   @Override
-  TimeSeries getOrCreateTimeSeries(List<String> labelValues);
+  Handle getHandle(List<String> labelValues);
 
   @Override
-  TimeSeries getDefaultTimeSeries();
+  Handle getDefaultHandle();
 
   /**
-   * The value of a single point in the Cumulative.TimeSeries.
+   * A {@code Handle} for a {@code CounterLong}.
    *
    * @since 0.1.0
    */
-  interface TimeSeries {
+  interface Handle {
 
     /**
      * Adds the given value to the current value. The values cannot be negative.

api/src/main/java/io/opentelemetry/metrics/DefaultMeter.java

@@ -100,22 +100,22 @@ public final class DefaultMeter implements Meter {
   private static final class NoopGaugeLong implements GaugeLong {
     private final int labelKeysSize;
 
-    /** Creates a new {@code NoopTimeSeries}. */
+    /** Creates a new {@code NoopHandle}. */
     private NoopGaugeLong(int labelKeysSize) {
       this.labelKeysSize = labelKeysSize;
     }
 
     @Override
-    public NoopTimeSeries getOrCreateTimeSeries(List<String> labelValues) {
+    public NoopHandle getHandle(List<String> labelValues) {
       Utils.checkNotNull(labelValues, "labelValues");
       Utils.checkArgument(
           labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
-      return new NoopTimeSeries();
+      return new NoopHandle();
     }
 
     @Override
-    public NoopTimeSeries getDefaultTimeSeries() {
+    public NoopHandle getDefaultHandle() {
-      return new NoopTimeSeries();
+      return new NoopHandle();
     }
 
     @Override
@@ -124,16 +124,16 @@ public final class DefaultMeter implements Meter {
     }
 
     @Override
-    public void removeTimeSeries(List<String> labelValues) {
+    public void removeHandle(List<String> labelValues) {
       Utils.checkNotNull(labelValues, "labelValues");
     }
 
     @Override
     public void clear() {}
 
-    /** No-op implementations of TimeSeries class. */
+    /** No-op implementations of Handle class. */
-    private static final class NoopTimeSeries implements TimeSeries {
+    private static final class NoopHandle implements Handle {
-      private NoopTimeSeries() {}
+      private NoopHandle() {}
 
       @Override
       public void add(long amt) {}
@@ -194,22 +194,22 @@ public final class DefaultMeter implements Meter {
   private static final class NoopGaugeDouble implements GaugeDouble {
     private final int labelKeysSize;
 
-    /** Creates a new {@code NoopTimeSeries}. */
+    /** Creates a new {@code NoopHandle}. */
     private NoopGaugeDouble(int labelKeysSize) {
       this.labelKeysSize = labelKeysSize;
     }
 
     @Override
-    public NoopTimeSeries getOrCreateTimeSeries(List<String> labelValues) {
+    public NoopHandle getHandle(List<String> labelValues) {
       Utils.checkNotNull(labelValues, "labelValues");
       Utils.checkArgument(
           labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
-      return new NoopTimeSeries();
+      return new NoopHandle();
     }
 
     @Override
-    public NoopTimeSeries getDefaultTimeSeries() {
+    public NoopHandle getDefaultHandle() {
-      return new NoopTimeSeries();
+      return new NoopHandle();
     }
 
     @Override
@@ -218,16 +218,16 @@ public final class DefaultMeter implements Meter {
     }
 
     @Override
-    public void removeTimeSeries(List<String> labelValues) {
+    public void removeHandle(List<String> labelValues) {
       Utils.checkNotNull(labelValues, "labelValues");
     }
 
     @Override
     public void clear() {}
 
-    /** No-op implementations of TimeSeries class. */
+    /** No-op implementations of Handle class. */
-    private static final class NoopTimeSeries implements TimeSeries {
+    private static final class NoopHandle implements Handle {
-      private NoopTimeSeries() {}
+      private NoopHandle() {}
 
       @Override
       public void add(double amt) {}
@@ -288,22 +288,22 @@ public final class DefaultMeter implements Meter {
   private static final class NoopCounterDouble implements CounterDouble {
     private final int labelKeysSize;
 
-    /** Creates a new {@code NoopTimeSeries}. */
+    /** Creates a new {@code NoopHandle}. */
     private NoopCounterDouble(int labelKeysSize) {
       this.labelKeysSize = labelKeysSize;
     }
 
     @Override
-    public NoopTimeSeries getOrCreateTimeSeries(List<String> labelValues) {
+    public NoopHandle getHandle(List<String> labelValues) {
       Utils.checkNotNull(labelValues, "labelValues");
       Utils.checkArgument(
           labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
-      return NoopTimeSeries.INSTANCE;
+      return NoopHandle.INSTANCE;
     }
 
     @Override
-    public NoopTimeSeries getDefaultTimeSeries() {
+    public NoopHandle getDefaultHandle() {
-      return NoopTimeSeries.INSTANCE;
+      return NoopHandle.INSTANCE;
     }
 
     @Override
@@ -312,18 +312,18 @@ public final class DefaultMeter implements Meter {
     }
 
     @Override
-    public void removeTimeSeries(List<String> labelValues) {
+    public void removeHandle(List<String> labelValues) {
       Utils.checkNotNull(labelValues, "labelValues");
     }
 
     @Override
     public void clear() {}
 
-    /** No-op implementations of TimeSeries class. */
+    /** No-op implementations of Handle class. */
-    private static final class NoopTimeSeries implements TimeSeries {
+    private static final class NoopHandle implements Handle {
-      private static final NoopTimeSeries INSTANCE = new NoopTimeSeries();
+      private static final NoopHandle INSTANCE = new NoopHandle();
 
-      private NoopTimeSeries() {}
+      private NoopHandle() {}
 
       @Override
       public void add(double delta) {}
@@ -384,22 +384,22 @@ public final class DefaultMeter implements Meter {
   private static final class NoopCounterLong implements CounterLong {
     private final int labelKeysSize;
 
-    /** Creates a new {@code NoopTimeSeries}. */
+    /** Creates a new {@code NoopHandle}. */
     private NoopCounterLong(int labelKeysSize) {
       this.labelKeysSize = labelKeysSize;
     }
 
     @Override
-    public NoopTimeSeries getOrCreateTimeSeries(List<String> labelValues) {
+    public NoopHandle getHandle(List<String> labelValues) {
       Utils.checkNotNull(labelValues, "labelValues");
       Utils.checkArgument(
           labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
-      return NoopTimeSeries.INSTANCE;
+      return NoopHandle.INSTANCE;
     }
 
     @Override
-    public NoopTimeSeries getDefaultTimeSeries() {
+    public NoopHandle getDefaultHandle() {
-      return NoopTimeSeries.INSTANCE;
+      return NoopHandle.INSTANCE;
     }
 
     @Override
@@ -408,18 +408,18 @@ public final class DefaultMeter implements Meter {
     }
 
     @Override
-    public void removeTimeSeries(List<String> labelValues) {
+    public void removeHandle(List<String> labelValues) {
       Utils.checkNotNull(labelValues, "labelValues");
     }
 
     @Override
     public void clear() {}
 
-    /** No-op implementations of TimeSeries class. */
+    /** No-op implementations of Handle class. */
-    private static final class NoopTimeSeries implements TimeSeries {
+    private static final class NoopHandle implements Handle {
-      private static final NoopTimeSeries INSTANCE = new NoopTimeSeries();
+      private static final NoopHandle INSTANCE = new NoopHandle();
 
-      private NoopTimeSeries() {}
+      private NoopHandle() {}
 
       @Override
       public void add(long delta) {}

api/src/main/java/io/opentelemetry/metrics/GaugeDouble.java

@@ -16,7 +16,7 @@
 
 package io.opentelemetry.metrics;
 
-import io.opentelemetry.metrics.GaugeDouble.TimeSeries;
+import io.opentelemetry.metrics.GaugeDouble.Handle;
 import java.util.List;
 import javax.annotation.concurrent.ThreadSafe;
 
@@ -37,19 +37,19 @@ import javax.annotation.concurrent.ThreadSafe;
  *           .setUnit("1")
  *           .setLabelKeys(Collections.singletonList("Key"))
  *           .build();
- *   // It is recommended to keep a reference of a TimeSeries.
+ *   // It is recommended to keep a reference of a Handle.
- *   private static final GaugeDouble.TimeSeries inboundTimeSeries =
+ *   private static final GaugeDouble.Handle inboundHandle =
- *       gauge.getOrCreateTimeSeries(Collections.singletonList("SomeWork"));
+ *       gauge.getHandle(Collections.singletonList("SomeWork"));
- *    private static final GaugeDouble.TimeSeries defaultTimeSeries = gauge.getDefaultTimeSeries();
+ *    private static final GaugeDouble.Handle defaultHandle = gauge.getDefaultHandle();
  *
  *   void doDefault() {
  *      // Your code here.
- *      defaultTimeSeries.add(10);
+ *      defaultHandle.add(10);
  *   }
  *
  *   void doSomeWork() {
  *      // Your code here.
- *      inboundTimeSeries.set(15);
+ *      inboundHandle.set(15);
  *   }
  *
  * }
@@ -58,20 +58,20 @@ import javax.annotation.concurrent.ThreadSafe;
  * @since 0.1.0
  */
 @ThreadSafe
-public interface GaugeDouble extends Metric<TimeSeries> {
+public interface GaugeDouble extends Metric<Handle> {
 
   @Override
-  TimeSeries getOrCreateTimeSeries(List<String> labelValues);
+  Handle getHandle(List<String> labelValues);
 
   @Override
-  TimeSeries getDefaultTimeSeries();
+  Handle getDefaultHandle();
 
   /**
-   * A {@code TimeSeries} for a {@code GaugeDouble}.
+   * A {@code Handle} for a {@code GaugeDouble}.
    *
    * @since 0.1.0
    */
-  interface TimeSeries {
+  interface Handle {
 
     /**
      * Adds the given value to the current value. The values can be negative.

api/src/main/java/io/opentelemetry/metrics/GaugeLong.java

@@ -16,6 +16,7 @@
 
 package io.opentelemetry.metrics;
 
+import io.opentelemetry.metrics.GaugeLong.Handle;
 import java.util.List;
 import javax.annotation.concurrent.ThreadSafe;
 
@@ -36,19 +37,19 @@ import javax.annotation.concurrent.ThreadSafe;
  *           .setUnit("1")
  *           .setLabelKeys(Collections.singletonList("Key"))
  *           .build();
- *   // It is recommended to keep a reference of a TimeSeries.
+ *   // It is recommended to keep a reference of a Handle.
- *   private static final GaugeLong.TimeSeries inboundTimeSeries =
+ *   private static final GaugeLong.Handle inboundHandle =
- *       gauge.getOrCreateTimeSeries(Collections.singletonList("SomeWork"));
+ *       gauge.getHandle(Collections.singletonList("SomeWork"));
- *    private static final GaugeLong.TimeSeries defaultTimeSeries = gauge.getDefaultTimeSeries();
+ *    private static final GaugeLong.Handle defaultHandle = gauge.getDefaultHandle();
  *
  *   void doDefault() {
  *      // Your code here.
- *      defaultTimeSeries.add(10);
+ *      defaultHandle.add(10);
  *   }
  *
  *   void doSomeWork() {
  *      // Your code here.
- *      inboundTimeSeries.set(15);
+ *      inboundHandle.set(15);
  *   }
  *
  * }
@@ -57,20 +58,20 @@ import javax.annotation.concurrent.ThreadSafe;
  * @since 0.1.0
  */
 @ThreadSafe
-public interface GaugeLong extends Metric<GaugeLong.TimeSeries> {
+public interface GaugeLong extends Metric<Handle> {
 
   @Override
-  TimeSeries getOrCreateTimeSeries(List<String> labelValues);
+  Handle getHandle(List<String> labelValues);
 
   @Override
-  TimeSeries getDefaultTimeSeries();
+  Handle getDefaultHandle();
 
   /**
-   * The value of a single point in the Gauge.TimeSeries.
+   * A {@code Handle} for a {@code GaugeLong}.
    *
    * @since 0.1.0
    */
-  interface TimeSeries {
+  interface Handle {
 
     /**
      * Adds the given value to the current value. The values can be negative.

api/src/main/java/io/opentelemetry/metrics/Measure.java

@@ -64,7 +64,7 @@ public interface Measure {
     B setUnit(String unit);
 
     /**
-     * Sets the map of constant labels (they will be added to all the TimeSeries) for the Metric.
+     * Sets the map of constant labels (they will be added to all the Handle) for the Metric.
      *
      * <p>Default value is {@link Collections#emptyMap()}.
      *

api/src/main/java/io/opentelemetry/metrics/Meter.java

@@ -70,7 +70,7 @@ import javax.annotation.concurrent.ThreadSafe;
  *             for (GarbageCollectorMXBean gc : ManagementFactory.getGarbageCollectorMXBeans()) {
  *               LabelValue gcName = LabelValue.create(gc.getName());
  *               collectionMetric
- *                   .getOrCreateTimeSeries(Collections.singletonList(gcName))
+ *                   .getHandle(Collections.singletonList(gcName))
  *                   .set(gc.getCollectionTime());
  *             }
  *           }
@@ -94,16 +94,16 @@ import javax.annotation.concurrent.ThreadSafe;
  *           .setLabelKeys(labelKeys)
  *           .build();
  *
- *   // It is recommended to keep a reference of a TimeSeries.
+ *   // It is recommended to keep a reference of a Handle.
- *   GaugeDouble.TimeSeries inboundTimeSeries = gauge.getOrCreateTimeSeries(labelValues);
+ *   GaugeDouble.Handle inboundHandle = gauge.getHandle(labelValues);
  *
  *   void doAddElement() {
  *      // Your code here.
- *      inboundTimeSeries.add(1);
+ *      inboundHandle.add(1);
  *   }
  *
  *   void doRemoveElement() {
- *      inboundTimeSeries.add(-1);
+ *      inboundHandle.add(-1);
  *      // Your code here.
  *   }
  *

api/src/main/java/io/opentelemetry/metrics/Metric.java

@@ -30,31 +30,30 @@ import javax.annotation.concurrent.ThreadSafe;
 @ThreadSafe
 public interface Metric<T> {
   /**
-   * Creates a {@code TimeSeries} and returns a {@code TimeSeries} if the specified {@code
+   * Returns a {@code Handle} with associated with specified {@code labelValues}. Multiples requests
-   * labelValues} is not already associated with this gauge, else returns an existing {@code
+   * with the same {@code labelValues} may return the same {@code Handle}.
-   * TimeSeries}.
    *
-   * <p>It is recommended to keep a reference to the TimeSeries instead of always calling this
+   * <p>It is recommended to keep a reference to the Handle instead of always calling this method
-   * method for every operations.
+   * for every operations.
    *
    * @param labelValues the list of label values. The number of label values must be the same to
    *     that of the label keys passed to {@link GaugeDouble.Builder#setLabelKeys(List)}.
-   * @return a {@code TimeSeries} the value of single gauge.
+   * @return a {@code Handle} the value of single gauge.
    * @throws NullPointerException if {@code labelValues} is null OR any element of {@code
    *     labelValues} is null.
    * @throws IllegalArgumentException if number of {@code labelValues}s are not equal to the label
    *     keys.
    * @since 0.1.0
    */
-  T getOrCreateTimeSeries(List<String> labelValues);
+  T getHandle(List<String> labelValues);
 
   /**
-   * Returns a {@code TimeSeries} for a metric with all labels not set (default label value).
+   * Returns a {@code Handle} for a metric with all labels not set.
    *
-   * @return a {@code TimeSeries} for a metric with all labels not set (default label value).
+   * @return a {@code Handle} for a metric with all labels not set.
    * @since 0.1.0
    */
-  T getDefaultTimeSeries();
+  T getDefaultHandle();
 
   /**
    * Sets a callback that gets executed every time before exporting this metric.
@@ -68,19 +67,19 @@ public interface Metric<T> {
   void setCallback(Runnable metricUpdater);
 
   /**
-   * Removes the {@code TimeSeries} from the metric, if it is present. i.e. references to previous
+   * Removes the {@code Handle} from the metric, if it is present. i.e. references to previous
-   * {@code TimeSeries} are invalid (not part of the metric).
+   * {@code Handle} are invalid (not part of the metric).
    *
    * <p>If value is missing for one of the predefined keys {@code null} must be used for that value.
    *
    * @param labelValues the list of label values.
    * @since 0.1.0
    */
-  void removeTimeSeries(List<String> labelValues);
+  void removeHandle(List<String> labelValues);
 
   /**
-   * Removes all {@code TimeSeries} from the metric. i.e. references to all previous {@code
+   * Removes all {@code Handle} from the metric. i.e. references to all previous {@code Handle} are
-   * TimeSeries} are invalid (not part of the metric).
+   * invalid (not part of the metric).
    *
    * @since 0.1.0
    */
@@ -118,7 +117,7 @@ public interface Metric<T> {
     B setLabelKeys(List<String> labelKeys);
 
     /**
-     * Sets the map of constant labels (they will be added to all the TimeSeries) for the Metric.
+     * Sets the map of constant labels (they will be added to all the Handle) for the Metric.
      *
      * <p>Default value is {@link Collections#emptyMap()}.
      *

api/src/test/java/io/opentelemetry/metrics/CounterDoubleTest.java

@@ -39,7 +39,7 @@ public class CounterDoubleTest {
   private final Meter meter = OpenTelemetry.getMeter();
 
   @Test
-  public void noopGetOrCreateTimeSeries_WithNullLabelValues() {
+  public void noopGetHandle_WithNullLabelValues() {
     CounterDouble counterDouble =
         meter
             .counterDoubleBuilder(NAME)
@@ -49,11 +49,11 @@ public class CounterDoubleTest {
             .build();
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("labelValues");
-    counterDouble.getOrCreateTimeSeries(null);
+    counterDouble.getHandle(null);
   }
 
   @Test
-  public void noopGetOrCreateTimeSeries_WithInvalidLabelSize() {
+  public void noopGetHandle_WithInvalidLabelSize() {
     CounterDouble counterDouble =
         meter
             .counterDoubleBuilder(NAME)
@@ -63,11 +63,11 @@ public class CounterDoubleTest {
             .build();
     thrown.expect(IllegalArgumentException.class);
     thrown.expectMessage("Label Keys and Label Values don't have same size.");
-    counterDouble.getOrCreateTimeSeries(EMPTY_LABEL_VALUES);
+    counterDouble.getHandle(EMPTY_LABEL_VALUES);
   }
 
   @Test
-  public void noopRemoveTimeSeries_WithNullLabelValues() {
+  public void noopRemoveHandle_WithNullLabelValues() {
     CounterDouble counterDouble =
         meter
             .counterDoubleBuilder(NAME)
@@ -77,6 +77,6 @@ public class CounterDoubleTest {
             .build();
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("labelValues");
-    counterDouble.removeTimeSeries(null);
+    counterDouble.removeHandle(null);
   }
 }

api/src/test/java/io/opentelemetry/metrics/CounterLongTest.java

@@ -39,7 +39,7 @@ public class CounterLongTest {
   private final Meter meter = OpenTelemetry.getMeter();
 
   @Test
-  public void noopGetOrCreateTimeSeries_WithNullLabelValues() {
+  public void noopGetHandle_WithNullLabelValues() {
     CounterLong counterLong =
         meter
             .counterLongBuilder(NAME)
@@ -49,11 +49,11 @@ public class CounterLongTest {
             .build();
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("labelValues");
-    counterLong.getOrCreateTimeSeries(null);
+    counterLong.getHandle(null);
   }
 
   @Test
-  public void noopGetOrCreateTimeSeries_WithInvalidLabelSize() {
+  public void noopGetHandle_WithInvalidLabelSize() {
     CounterLong counterLong =
         meter
             .counterLongBuilder(NAME)
@@ -63,11 +63,11 @@ public class CounterLongTest {
             .build();
     thrown.expect(IllegalArgumentException.class);
     thrown.expectMessage("Label Keys and Label Values don't have same size.");
-    counterLong.getOrCreateTimeSeries(EMPTY_LABEL_VALUES);
+    counterLong.getHandle(EMPTY_LABEL_VALUES);
   }
 
   @Test
-  public void noopRemoveTimeSeries_WithNullLabelValues() {
+  public void noopRemoveHandle_WithNullLabelValues() {
     CounterLong counterLong =
         meter
             .counterLongBuilder(NAME)
@@ -77,6 +77,6 @@ public class CounterLongTest {
             .build();
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("labelValues");
-    counterLong.removeTimeSeries(null);
+    counterLong.removeHandle(null);
   }
 }

api/src/test/java/io/opentelemetry/metrics/GaugeDoubleTest.java

@@ -39,7 +39,7 @@ public class GaugeDoubleTest {
   private final Meter meter = OpenTelemetry.getMeter();
 
   @Test
-  public void noopGetOrCreateTimeSeries_WithNullLabelValues() {
+  public void noopGetHandle_WithNullLabelValues() {
     GaugeDouble gaugeDouble =
         meter
             .gaugeDoubleBuilder(NAME)
@@ -49,11 +49,11 @@ public class GaugeDoubleTest {
             .build();
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("labelValues");
-    gaugeDouble.getOrCreateTimeSeries(null);
+    gaugeDouble.getHandle(null);
   }
 
   @Test
-  public void noopGetOrCreateTimeSeries_WithInvalidLabelSize() {
+  public void noopGetHandle_WithInvalidLabelSize() {
     GaugeDouble gaugeDouble =
         meter
             .gaugeDoubleBuilder(NAME)
@@ -63,11 +63,11 @@ public class GaugeDoubleTest {
             .build();
     thrown.expect(IllegalArgumentException.class);
     thrown.expectMessage("Label Keys and Label Values don't have same size.");
-    gaugeDouble.getOrCreateTimeSeries(EMPTY_LABEL_VALUES);
+    gaugeDouble.getHandle(EMPTY_LABEL_VALUES);
   }
 
   @Test
-  public void noopRemoveTimeSeries_WithNullLabelValues() {
+  public void noopRemoveHandle_WithNullLabelValues() {
     GaugeDouble gaugeDouble =
         meter
             .gaugeDoubleBuilder(NAME)
@@ -77,6 +77,6 @@ public class GaugeDoubleTest {
             .build();
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("labelValues");
-    gaugeDouble.removeTimeSeries(null);
+    gaugeDouble.removeHandle(null);
   }
 }

api/src/test/java/io/opentelemetry/metrics/GaugeLongTest.java

@@ -39,7 +39,7 @@ public class GaugeLongTest {
   private final Meter meter = OpenTelemetry.getMeter();
 
   @Test
-  public void noopGetOrCreateTimeSeries_WithNullLabelValues() {
+  public void noopGetHandle_WithNullLabelValues() {
     GaugeLong gaugeLong =
         meter
             .gaugeLongBuilder(NAME)
@@ -49,11 +49,11 @@ public class GaugeLongTest {
             .build();
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("labelValues");
-    gaugeLong.getOrCreateTimeSeries(null);
+    gaugeLong.getHandle(null);
   }
 
   @Test
-  public void noopGetOrCreateTimeSeries_WithInvalidLabelSize() {
+  public void noopGetHandle_WithInvalidLabelSize() {
     GaugeLong gaugeLong =
         meter
             .gaugeLongBuilder(NAME)
@@ -63,11 +63,11 @@ public class GaugeLongTest {
             .build();
     thrown.expect(IllegalArgumentException.class);
     thrown.expectMessage("Label Keys and Label Values don't have same size.");
-    gaugeLong.getOrCreateTimeSeries(EMPTY_LABEL_VALUES);
+    gaugeLong.getHandle(EMPTY_LABEL_VALUES);
   }
 
   @Test
-  public void noopRemoveTimeSeries_WithNullLabelValues() {
+  public void noopRemoveHandle_WithNullLabelValues() {
     GaugeLong gaugeLong =
         meter
             .gaugeLongBuilder(NAME)
@@ -77,6 +77,6 @@ public class GaugeLongTest {
             .build();
     thrown.expect(NullPointerException.class);
     thrown.expectMessage("labelValues");
-    gaugeLong.removeTimeSeries(null);
+    gaugeLong.removeHandle(null);
   }
 }

contrib/runtime_metrics/src/main/java/io/opentelemetry/contrib/metrics/runtime/GarbageCollector.java

@@ -69,7 +69,7 @@ public final class GarbageCollector {
           public void run() {
             for (final GarbageCollectorMXBean gc : garbageCollectors) {
               collectionMetric
-                  .getOrCreateTimeSeries(Collections.singletonList(gc.getName()))
+                  .getHandle(Collections.singletonList(gc.getName()))
                   .set(gc.getCollectionTime());
             }
           }

contrib/runtime_metrics/src/main/java/io/opentelemetry/contrib/metrics/runtime/MemoryPools.java

@@ -18,6 +18,7 @@ package io.opentelemetry.contrib.metrics.runtime;
 
 import io.opentelemetry.OpenTelemetry;
 import io.opentelemetry.metrics.GaugeLong;
+import io.opentelemetry.metrics.GaugeLong.Handle;
 import io.opentelemetry.metrics.Meter;
 import java.lang.management.ManagementFactory;
 import java.lang.management.MemoryMXBean;
@@ -78,18 +79,13 @@ public final class MemoryPools {
             .setLabelKeys(Arrays.asList(TYPE_LABEL_KEY, AREA_LABEL_KEY))
             .setComponent("jvm_memory")
             .build();
-    final GaugeLong.TimeSeries usedHeap =
+    final Handle usedHeap = areaMetric.getHandle(Arrays.asList(USED, HEAP));
-        areaMetric.getOrCreateTimeSeries(Arrays.asList(USED, HEAP));
+    final Handle usedNonHeap = areaMetric.getHandle(Arrays.asList(USED, NON_HEAP));
-    final GaugeLong.TimeSeries usedNonHeap =
+    final Handle committedHeap = areaMetric.getHandle(Arrays.asList(COMMITTED, HEAP));
-        areaMetric.getOrCreateTimeSeries(Arrays.asList(USED, NON_HEAP));
+    final Handle committedNonHeap = areaMetric.getHandle(Arrays.asList(COMMITTED, NON_HEAP));
-    final GaugeLong.TimeSeries committedHeap =
-        areaMetric.getOrCreateTimeSeries(Arrays.asList(COMMITTED, HEAP));
-    final GaugeLong.TimeSeries committedNonHeap =
-        areaMetric.getOrCreateTimeSeries(Arrays.asList(COMMITTED, NON_HEAP));
     // TODO: Decide if max is needed or not. May be derived with some approximation from max(used).
-    final GaugeLong.TimeSeries maxHeap = areaMetric.getOrCreateTimeSeries(Arrays.asList(MAX, HEAP));
+    final Handle maxHeap = areaMetric.getHandle(Arrays.asList(MAX, HEAP));
-    final GaugeLong.TimeSeries maxNonHeap =
+    final Handle maxNonHeap = areaMetric.getHandle(Arrays.asList(MAX, NON_HEAP));
-        areaMetric.getOrCreateTimeSeries(Arrays.asList(MAX, NON_HEAP));
     areaMetric.setCallback(
         new Runnable() {
           @Override
@@ -122,17 +118,13 @@ public final class MemoryPools {
           public void run() {
             for (final MemoryPoolMXBean pool : poolBeans) {
               MemoryUsage poolUsage = pool.getUsage();
+              poolMetric.getHandle(Arrays.asList(USED, pool.getName())).set(poolUsage.getUsed());
               poolMetric
-                  .getOrCreateTimeSeries(Arrays.asList(USED, pool.getName()))
+                  .getHandle(Arrays.asList(COMMITTED, pool.getName()))
-                  .set(poolUsage.getUsed());
-              poolMetric
-                  .getOrCreateTimeSeries(Arrays.asList(COMMITTED, pool.getName()))
                   .set(poolUsage.getUsed());
               // TODO: Decide if max is needed or not. May be derived with some approximation from
               //  max(used).
-              poolMetric
+              poolMetric.getHandle(Arrays.asList(MAX, pool.getName())).set(poolUsage.getUsed());
-                  .getOrCreateTimeSeries(Arrays.asList(MAX, pool.getName()))
-                  .set(poolUsage.getUsed());
             }
           }
         });