Rename .observe to .record (#3949)

* Rename .observe to .record * Apply deprecation
open-telemetry · Dec 2, 2021 · b1651a1 · b1651a1
1 parent 56e1b90
commit b1651a1
Show file tree

Hide file tree

Showing 19 changed files with 120 additions and 71 deletions.
diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/ObservableDoubleMeasurement.java b/api/all/src/main/java/io/opentelemetry/api/metrics/ObservableDoubleMeasurement.java
@@ -12,15 +12,38 @@ public interface ObservableDoubleMeasurement extends ObservableMeasurement {
   /**
    * Records a measurement.
    *
-   * @param value The measurement amount. MUST be non-negative.
+   * @param value The measurement amount.
+   * @deprecated Use {@link #record(double)}.
    */
-  void observe(double value);
+  @Deprecated
+  default void observe(double value) {
+    record(value);
+  }
 
   /**
    * Records a measurement with a set of attributes.
    *
-   * @param value The measurement amount. MUST be non-negative.
+   * @param value The measurement amount.
    * @param attributes A set of attributes to associate with the count.
+   * @deprecated Use {@link #record(double, Attributes)}.
    */
-  void observe(double value, Attributes attributes);
+  @Deprecated
+  default void observe(double value, Attributes attributes) {
+    record(value, attributes);
+  }
+
+  /**
+   * Records a measurement.
+   *
+   * @param value The measurement amount.
+   */
+  void record(double value);
+
+  /**
+   * Records a measurement with a set of attributes.
+   *
+   * @param value The measurement amount.
+   * @param attributes A set of attributes to associate with the count.
+   */
+  void record(double value, Attributes attributes);
 }
diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/ObservableLongMeasurement.java b/api/all/src/main/java/io/opentelemetry/api/metrics/ObservableLongMeasurement.java
@@ -12,15 +12,38 @@ public interface ObservableLongMeasurement extends ObservableMeasurement {
   /**
    * Records a measurement.
    *
-   * @param value The measurement amount. MUST be non-negative.
+   * @param value The measurement amount.
+   * @deprecated Use {@link #record(long)}.
    */
-  void observe(long value);
+  @Deprecated
+  default void observe(long value) {
+    record(value);
+  }
 
   /**
    * Records a measurement with a set of attributes.
    *
-   * @param value The measurement amount. MUST be non-negative.
+   * @param value The measurement amount.
    * @param attributes A set of attributes to associate with the count.
+   * @deprecated Use {@link #record(long, Attributes)}.
    */
-  void observe(long value, Attributes attributes);
+  @Deprecated
+  default void observe(long value, Attributes attributes) {
+    record(value, attributes);
+  }
+
+  /**
+   * Records a measurement.
+   *
+   * @param value The measurement amount.
+   */
+  void record(long value);
+
+  /**
+   * Records a measurement with a set of attributes.
+   *
+   * @param value The measurement amount.
+   * @param attributes A set of attributes to associate with the count.
+   */
+  void record(long value, Attributes attributes);
 }
diff --git a/api/all/src/test/java/io/opentelemetry/api/metrics/DefaultMeterTest.java b/api/all/src/test/java/io/opentelemetry/api/metrics/DefaultMeterTest.java
@@ -100,8 +100,8 @@ void noopObservableLongGauage_doesNotThrow() {
         .setUnit("C")
         .buildWithCallback(
             m -> {
-              m.observe(1);
-              m.observe(2, Attributes.of(stringKey("thing"), "engine"));
+              m.record(1);
+              m.record(2, Attributes.of(stringKey("thing"), "engine"));
             });
   }
 
@@ -113,8 +113,8 @@ void noopObservableDoubleGauage_doesNotThrow() {
         .setUnit("C")
         .buildWithCallback(
             m -> {
-              m.observe(1.0e1);
-              m.observe(-27.4, Attributes.of(stringKey("thing"), "engine"));
+              m.record(1.0e1);
+              m.record(-27.4, Attributes.of(stringKey("thing"), "engine"));
             });
   }
 
@@ -126,8 +126,8 @@ void noopObservableLongCounter_doesNotThrow() {
         .setUnit("C")
         .buildWithCallback(
             m -> {
-              m.observe(1);
-              m.observe(2, Attributes.of(stringKey("thing"), "engine"));
+              m.record(1);
+              m.record(2, Attributes.of(stringKey("thing"), "engine"));
             });
   }
 
@@ -140,8 +140,8 @@ void noopObservableDoubleCounter_doesNotThrow() {
         .setUnit("C")
         .buildWithCallback(
             m -> {
-              m.observe(1.0e1);
-              m.observe(-27.4, Attributes.of(stringKey("thing"), "engine"));
+              m.record(1.0e1);
+              m.record(-27.4, Attributes.of(stringKey("thing"), "engine"));
             });
   }
 
@@ -153,8 +153,8 @@ void noopObservableLongUpDownCounter_doesNotThrow() {
         .setUnit("C")
         .buildWithCallback(
             m -> {
-              m.observe(1);
-              m.observe(2, Attributes.of(stringKey("thing"), "engine"));
+              m.record(1);
+              m.record(2, Attributes.of(stringKey("thing"), "engine"));
             });
   }
 
@@ -167,8 +167,8 @@ void noopObservableDoubleUpDownCounter_doesNotThrow() {
         .setUnit("C")
         .buildWithCallback(
             m -> {
-              m.observe(1.0e1);
-              m.observe(-27.4, Attributes.of(stringKey("thing"), "engine"));
+              m.record(1.0e1);
+              m.record(-27.4, Attributes.of(stringKey("thing"), "engine"));
             });
   }
 }
diff --git a/docs/apidiffs/current_vs_latest/opentelemetry-api.txt b/docs/apidiffs/current_vs_latest/opentelemetry-api.txt
@@ -164,14 +164,22 @@ Comparing source compatibility of  against
 	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
 	+++  NEW INTERFACE: io.opentelemetry.api.metrics.ObservableMeasurement
 	+++  NEW SUPERCLASS: java.lang.Object
-	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void observe(double)
-	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void observe(double, io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void observe(double)
+		+++  NEW ANNOTATION: java.lang.Deprecated
+	+++  NEW METHOD: PUBLIC(+) void observe(double, io.opentelemetry.api.common.Attributes)
+		+++  NEW ANNOTATION: java.lang.Deprecated
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void record(double)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void record(double, io.opentelemetry.api.common.Attributes)
 +++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.metrics.ObservableLongMeasurement  (not serializable)
 	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
 	+++  NEW INTERFACE: io.opentelemetry.api.metrics.ObservableMeasurement
 	+++  NEW SUPERCLASS: java.lang.Object
-	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void observe(long)
-	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void observe(long, io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void observe(long)
+		+++  NEW ANNOTATION: java.lang.Deprecated
+	+++  NEW METHOD: PUBLIC(+) void observe(long, io.opentelemetry.api.common.Attributes)
+		+++  NEW ANNOTATION: java.lang.Deprecated
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void record(long)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void record(long, io.opentelemetry.api.common.Attributes)
 +++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.api.metrics.ObservableMeasurement  (not serializable)
 	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
 	+++  NEW SUPERCLASS: java.lang.Object

diff --git a/...s/otlp/common/src/jmh/java/io/opentelemetry/exporter/otlp/internal/GrpcGzipBenchmark.java b/...s/otlp/common/src/jmh/java/io/opentelemetry/exporter/otlp/internal/GrpcGzipBenchmark.java
@@ -82,7 +82,7 @@ public class GrpcGzipBenchmark {
         .ofLongs()
         .buildWithCallback(
             measurement ->
-                measurement.observe(5, Attributes.of(AttributeKey.stringKey("key"), "value")));
+                measurement.record(5, Attributes.of(AttributeKey.stringKey("key"), "value")));
     LongCounter longCounter =
         meter1
             .counterBuilder("counter")
@@ -107,7 +107,7 @@ public class GrpcGzipBenchmark {
         .gaugeBuilder("doublegauge")
         .setDescription("doublegauge")
         .setUnit("unit")
-        .buildWithCallback(measurement -> measurement.observe(5.0));
+        .buildWithCallback(measurement -> measurement.record(5.0));
     DoubleCounter doubleCounter = meter2.counterBuilder("doublecounter").ofDoubles().build();
     doubleCounter.add(1.0);
     doubleCounter.add(2.0);

diff --git a/...rc/jmh/java/io/opentelemetry/exporter/otlp/internal/MetricsRequestMarshalerBenchmark.java b/...rc/jmh/java/io/opentelemetry/exporter/otlp/internal/MetricsRequestMarshalerBenchmark.java
@@ -73,7 +73,7 @@ public class MetricsRequestMarshalerBenchmark {
         .ofLongs()
         .buildWithCallback(
             measurement ->
-                measurement.observe(5, Attributes.of(AttributeKey.stringKey("key"), "value")));
+                measurement.record(5, Attributes.of(AttributeKey.stringKey("key"), "value")));
     LongCounter longCounter =
         meter1
             .counterBuilder("counter")
@@ -98,7 +98,7 @@ public class MetricsRequestMarshalerBenchmark {
         .gaugeBuilder("doublegauge")
         .setDescription("doublegauge")
         .setUnit("unit")
-        .buildWithCallback(measurement -> measurement.observe(5.0));
+        .buildWithCallback(measurement -> measurement.record(5.0));
     DoubleCounter doubleCounter = meter2.counterBuilder("doublecounter").ofDoubles().build();
     doubleCounter.add(1.0);
     doubleCounter.add(2.0);

diff --git a/.../integrationTest/java/io/opentelemetry/exporter/prometheus/PrometheusIntegrationTest.java b/.../integrationTest/java/io/opentelemetry/exporter/prometheus/PrometheusIntegrationTest.java
@@ -85,7 +85,7 @@ void endToEnd() throws Exception {
     meter
         .gaugeBuilder("lives")
         .buildWithCallback(
-            result -> result.observe(9, Attributes.builder().put("animal", "cat").build()));
+            result -> result.record(9, Attributes.builder().put("animal", "cat").build()));
 
     WebClient promClient = WebClient.of("http://localhost:" + prometheus.getMappedPort(9090));
     JSON json = JSON.builder().treeCodec(new JacksonJrsTreeCodec()).build();

diff --git a/...oconfigure/src/testPrometheus/java/io/opentelemetry/sdk/autoconfigure/PrometheusTest.java b/...oconfigure/src/testPrometheus/java/io/opentelemetry/sdk/autoconfigure/PrometheusTest.java
@@ -39,7 +39,7 @@ void prometheusExporter() throws Exception {
         .get("test")
         .gaugeBuilder("test")
         .ofLongs()
-        .buildWithCallback(result -> result.observe(2, Attributes.empty()));
+        .buildWithCallback(result -> result.record(2, Attributes.empty()));
 
     WebClient client = WebClient.of("http://127.0.0.1:" + port);
     AggregatedHttpResponse response = client.get("/metrics").aggregate().join();

diff --git a/.../src/main/java/io/opentelemetry/sdk/metrics/internal/state/AsynchronousMetricStorage.java b/.../src/main/java/io/opentelemetry/sdk/metrics/internal/state/AsynchronousMetricStorage.java
@@ -69,7 +69,7 @@ public static <T> MetricStorage doubleAsynchronousAccumulator(
     final ObservableDoubleMeasurement result =
         new ObservableDoubleMeasurement() {
           @Override
-          public void observe(double value, Attributes attributes) {
+          public void record(double value, Attributes attributes) {
             T accumulation =
                 aggregator.accumulateDoubleMeasurement(value, attributes, Context.current());
             if (accumulation != null) {
@@ -79,8 +79,8 @@ public void observe(double value, Attributes attributes) {
           }
 
           @Override
-          public void observe(double value) {
-            observe(value, Attributes.empty());
+          public void record(double value) {
+            record(value, Attributes.empty());
           }
         };
     return new AsynchronousMetricStorage<>(
@@ -102,7 +102,7 @@ public static <T> MetricStorage longAsynchronousAccumulator(
         new ObservableLongMeasurement() {
 
           @Override
-          public void observe(long value, Attributes attributes) {
+          public void record(long value, Attributes attributes) {
             T accumulation =
                 aggregator.accumulateLongMeasurement(value, attributes, Context.current());
             if (accumulation != null) {
@@ -112,8 +112,8 @@ public void observe(long value, Attributes attributes) {
           }
 
           @Override
-          public void observe(long value) {
-            observe(value, Attributes.empty());
+          public void record(long value) {
+            record(value, Attributes.empty());
           }
         };
     return new AsynchronousMetricStorage<>(

diff --git a/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/CardinalityTest.java b/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/CardinalityTest.java
@@ -90,7 +90,7 @@ void staleMetricsDropped_asynchronousInstrument() {
         .counterBuilder("async-counter")
         .buildWithCallback(
             measurement ->
-                measurement.observe(
+                measurement.record(
                     1, Attributes.builder().put("key", "num_" + count.incrementAndGet()).build()));
 
     for (int i = 1; i <= 5; i++) {
@@ -181,7 +181,7 @@ void cardinalityLimits_asynchronousInstrument() {
     Consumer<ObservableLongMeasurement> callback =
         measurement -> {
           for (int i = 0; i < MAX_ACCUMULATIONS + 1; i++) {
-            measurement.observe(1, Attributes.builder().put("key", "value" + i).build());
+            measurement.record(1, Attributes.builder().put("key", "value" + i).build());
           }
         };
     meter.counterBuilder("async-counter1").buildWithCallback(callback);

diff --git a/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkDoubleGaugeBuilderTest.java b/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkDoubleGaugeBuilderTest.java
@@ -51,7 +51,7 @@ void collectMetrics_WithOneRecord() {
         .setDescription("My own DoubleValueObserver")
         .setUnit("ms")
         .buildWithCallback(
-            result -> result.observe(12.1d, Attributes.builder().put("k", "v").build()));
+            result -> result.record(12.1d, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofSeconds(1));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(

diff --git a/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkDoubleSumObserverTest.java b/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkDoubleSumObserverTest.java
@@ -59,7 +59,7 @@ void collectMetrics_WithOneRecord() {
         .setDescription("My own DoubleSumObserver")
         .setUnit("ms")
         .buildWithCallback(
-            result -> result.observe(12.1d, Attributes.builder().put("k", "v").build()));
+            result -> result.record(12.1d, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofNanos(SECOND_NANOS));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(
@@ -126,7 +126,7 @@ void collectMetrics_DeltaSumAggregator() {
         .setDescription("My own DoubleSumObserver")
         .setUnit("ms")
         .buildWithCallback(
-            result -> result.observe(12.1d, Attributes.builder().put("k", "v").build()));
+            result -> result.record(12.1d, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofNanos(SECOND_NANOS));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(

diff --git a/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkDoubleUpDownSumObserverTest.java b/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkDoubleUpDownSumObserverTest.java
@@ -57,7 +57,7 @@ void collectMetrics_WithOneRecord() {
         .upDownCounterBuilder("testObserver")
         .ofDoubles()
         .buildWithCallback(
-            result -> result.observe(12.1d, Attributes.builder().put("k", "v").build()));
+            result -> result.record(12.1d, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofNanos(SECOND_NANOS));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(
@@ -120,7 +120,7 @@ void collectMetrics_DeltaSumAggregator() {
         .upDownCounterBuilder("testObserver")
         .ofDoubles()
         .buildWithCallback(
-            result -> result.observe(12.1d, Attributes.builder().put("k", "v").build()));
+            result -> result.record(12.1d, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofNanos(SECOND_NANOS));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(

diff --git a/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkLongGaugeBuilderTest.java b/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkLongGaugeBuilderTest.java
@@ -50,8 +50,7 @@ void collectMetrics_WithOneRecord() {
     sdkMeter
         .gaugeBuilder("testObserver")
         .ofLongs()
-        .buildWithCallback(
-            result -> result.observe(12, Attributes.builder().put("k", "v").build()));
+        .buildWithCallback(result -> result.record(12, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofSeconds(1));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(

diff --git a/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkLongSumObserverTest.java b/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkLongSumObserverTest.java
@@ -54,8 +54,7 @@ void collectMetrics_WithOneRecord() {
     sdkMeterProvider
         .get(getClass().getName())
         .counterBuilder("testObserver")
-        .buildWithCallback(
-            result -> result.observe(12, Attributes.builder().put("k", "v").build()));
+        .buildWithCallback(result -> result.record(12, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofNanos(SECOND_NANOS));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(
@@ -116,8 +115,7 @@ void collectMetrics_DeltaSumAggregator() {
     sdkMeterProvider
         .get(getClass().getName())
         .counterBuilder("testObserver")
-        .buildWithCallback(
-            result -> result.observe(12, Attributes.builder().put("k", "v").build()));
+        .buildWithCallback(result -> result.record(12, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofNanos(SECOND_NANOS));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(

diff --git a/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkLongUpDownSumObserverTest.java b/sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkLongUpDownSumObserverTest.java
@@ -54,8 +54,7 @@ void collectMetrics_WithOneRecord() {
     sdkMeterProvider
         .get(getClass().getName())
         .upDownCounterBuilder("testObserver")
-        .buildWithCallback(
-            result -> result.observe(12, Attributes.builder().put("k", "v").build()));
+        .buildWithCallback(result -> result.record(12, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofNanos(SECOND_NANOS));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(
@@ -116,8 +115,7 @@ void collectMetrics_DeltaSumAggregator() {
     sdkMeterProvider
         .get(getClass().getName())
         .upDownCounterBuilder("testObserver")
-        .buildWithCallback(
-            result -> result.observe(12, Attributes.builder().put("k", "v").build()));
+        .buildWithCallback(result -> result.record(12, Attributes.builder().put("k", "v").build()));
     testClock.advance(Duration.ofNanos(SECOND_NANOS));
     assertThat(sdkMeterReader.collectAllMetrics())
         .satisfiesExactly(