Add batch callback API

api/all/src/main/java/io/opentelemetry/api/metrics/BatchCallback.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.metrics;
+
+/**
+ * A reference to a batch callback registered via {@link Meter#batchCallback(Runnable,
+ * ObservableMeasurement, ObservableMeasurement...)}.
+ */
+public interface BatchCallback extends AutoCloseable {
+
+  /**
+   * Remove the callback registered via {@link Meter#batchCallback(Runnable, ObservableMeasurement,
+   * ObservableMeasurement...)}. After this is called, the callback won't be invoked on future
+   * collections. Subsequent calls to {@link #close()} have no effect.
+   */
+  @Override
+  default void close() {}
+}

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

@@ -44,6 +44,11 @@ class DefaultMeter implements Meter {
   private static final DoubleHistogramBuilder NOOP_DOUBLE_HISTOGRAM_BUILDER =
       new NoopDoubleHistogramBuilder();
   private static final DoubleGaugeBuilder NOOP_DOUBLE_GAUGE_BUILDER = new NoopDoubleGaugeBuilder();
+  private static final BatchCallback NOOP_BATCH_CALLBACK = new BatchCallback() {};
+  private static final ObservableDoubleMeasurement NOOP_OBSERVABLE_DOUBLE_MEASUREMENT =
+      new NoopObservableDoubleMeasurement();
+  private static final ObservableLongMeasurement NOOP_OBSERVABLE_LONG_MEASUREMENT =
+      new NoopObservableLongMeasurement();
 
   static Meter getInstance() {
     return INSTANCE;
@@ -73,6 +78,14 @@ public DoubleGaugeBuilder gaugeBuilder(String name) {
     return NOOP_DOUBLE_GAUGE_BUILDER;
   }
 
+  @Override
+  public BatchCallback batchCallback(
+      Runnable callback,
+      ObservableMeasurement observableMeasurement,
+      ObservableMeasurement... additionalMeasurements) {
+    return NOOP_BATCH_CALLBACK;
+  }
+
   private DefaultMeter() {}
 
   private static class NoopLongCounter implements LongCounter {
@@ -129,6 +142,11 @@ public LongCounter build() {
     public ObservableLongCounter buildWithCallback(Consumer<ObservableLongMeasurement> callback) {
       return NOOP_OBSERVABLE_COUNTER;
     }
+
+    @Override
+    public ObservableLongMeasurement buildObserver() {
+      return NOOP_OBSERVABLE_LONG_MEASUREMENT;
+    }
   }
 
   private static class NoopDoubleCounterBuilder implements DoubleCounterBuilder {
@@ -157,6 +175,11 @@ public ObservableDoubleCounter buildWithCallback(
         Consumer<ObservableDoubleMeasurement> callback) {
       return NOOP_OBSERVABLE_COUNTER;
     }
+
+    @Override
+    public ObservableDoubleMeasurement buildObserver() {
+      return NOOP_OBSERVABLE_DOUBLE_MEASUREMENT;
+    }
   }
 
   private static class NoopLongUpDownCounter implements LongUpDownCounter {
@@ -214,6 +237,11 @@ public ObservableLongUpDownCounter buildWithCallback(
         Consumer<ObservableLongMeasurement> callback) {
       return NOOP_OBSERVABLE_UP_DOWN_COUNTER;
     }
+
+    @Override
+    public ObservableLongMeasurement buildObserver() {
+      return NOOP_OBSERVABLE_LONG_MEASUREMENT;
+    }
   }
 
   private static class NoopDoubleUpDownCounterBuilder implements DoubleUpDownCounterBuilder {
@@ -243,6 +271,11 @@ public ObservableDoubleUpDownCounter buildWithCallback(
         Consumer<ObservableDoubleMeasurement> callback) {
       return NOOP_OBSERVABLE_UP_DOWN_COUNTER;
     }
+
+    @Override
+    public ObservableDoubleMeasurement buildObserver() {
+      return NOOP_OBSERVABLE_DOUBLE_MEASUREMENT;
+    }
   }
 
   private static class NoopDoubleHistogram implements DoubleHistogram {
@@ -338,6 +371,11 @@ public LongGaugeBuilder ofLongs() {
     public ObservableDoubleGauge buildWithCallback(Consumer<ObservableDoubleMeasurement> callback) {
       return NOOP;
     }
+
+    @Override
+    public ObservableDoubleMeasurement buildObserver() {
+      return NOOP_OBSERVABLE_DOUBLE_MEASUREMENT;
+    }
   }
 
   private static class NoopLongGaugeBuilder implements LongGaugeBuilder {
@@ -358,5 +396,26 @@ public LongGaugeBuilder setUnit(String unit) {
     public ObservableLongGauge buildWithCallback(Consumer<ObservableLongMeasurement> callback) {
       return NOOP;
     }
+
+    @Override
+    public ObservableLongMeasurement buildObserver() {
+      return NOOP_OBSERVABLE_LONG_MEASUREMENT;
+    }
+  }
+
+  private static class NoopObservableDoubleMeasurement implements ObservableDoubleMeasurement {
+    @Override
+    public void record(double value) {}
+
+    @Override
+    public void record(double value, Attributes attributes) {}
+  }
+
+  private static class NoopObservableLongMeasurement implements ObservableLongMeasurement {
+    @Override
+    public void record(long value) {}
+
+    @Override
+    public void record(long value, Attributes attributes) {}
   }
 }

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java

@@ -35,7 +35,7 @@ public interface DoubleCounterBuilder {
   /**
    * Builds this asynchronous instrument with the given callback.
    *
-   * <p>The callback will only be called when the {@link Meter} is being observed.
+   * <p>The callback will be called when the {@link Meter} is being observed.
    *
    * <p>Callbacks are expected to abide by the following restrictions:
    *
@@ -48,4 +48,17 @@ public interface DoubleCounterBuilder {
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   ObservableDoubleCounter buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
+
+  /**
+   * Build an observer for this instrument to observe values from a {@link BatchCallback}.
+   *
+   * <p>This observer MUST be registered when creating a {@link Meter#batchCallback(Runnable,
+   * ObservableMeasurement, ObservableMeasurement...) batchCallback}, which records to it. Values
+   * observed outside registered callbacks are ignored.
+   *
+   * @return an observable measurement that batch callbacks use to observe values.
+   */
+  default ObservableDoubleMeasurement buildObserver() {
+    return DefaultMeter.getInstance().counterBuilder("noop").ofDoubles().buildObserver();
+  }
 }

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java

@@ -31,7 +31,7 @@ public interface DoubleGaugeBuilder {
   /**
    * Builds this asynchronous instrument with the given callback.
    *
-   * <p>The callback will only be called when the {@link Meter} is being observed.
+   * <p>The callback will be called when the {@link Meter} is being observed.
    *
    * <p>Callbacks are expected to abide by the following restrictions:
    *
@@ -43,4 +43,17 @@ public interface DoubleGaugeBuilder {
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   ObservableDoubleGauge buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
+
+  /**
+   * Build an observer for this instrument to observe values from a {@link BatchCallback}.
+   *
+   * <p>This observer MUST be registered when creating a {@link Meter#batchCallback(Runnable,
+   * ObservableMeasurement, ObservableMeasurement...) batchCallback}, which records to it. Values
+   * observed outside registered callbacks are ignored.
+   *
+   * @return an observable measurement that batch callbacks use to observe values.
+   */
+  default ObservableDoubleMeasurement buildObserver() {
+    return DefaultMeter.getInstance().gaugeBuilder("noop").buildObserver();
+  }
 }

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java

@@ -35,7 +35,7 @@ public interface DoubleUpDownCounterBuilder {
   /**
    * Builds this asynchronous instrument with the given callback.
    *
-   * <p>The callback will only be called when the {@link Meter} is being observed.
+   * <p>The callback will be called when the {@link Meter} is being observed.
    *
    * <p>Callbacks are expected to abide by the following restrictions:
    *
@@ -47,4 +47,17 @@ public interface DoubleUpDownCounterBuilder {
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   ObservableDoubleUpDownCounter buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
+
+  /**
+   * Build an observer for this instrument to observe values from a {@link BatchCallback}.
+   *
+   * <p>This observer MUST be registered when creating a {@link Meter#batchCallback(Runnable,
+   * ObservableMeasurement, ObservableMeasurement...) batchCallback}, which records to it. Values
+   * observed outside registered callbacks are ignored.
+   *
+   * @return an observable measurement that batch callbacks use to observe values.
+   */
+  default ObservableDoubleMeasurement buildObserver() {
+    return DefaultMeter.getInstance().upDownCounterBuilder("noop").ofDoubles().buildObserver();
+  }
 }

api/all/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java

@@ -39,7 +39,7 @@ public interface LongCounterBuilder {
   /**
    * Builds this asynchronous instrument with the given callback.
    *
-   * <p>The callback will only be called when the {@link Meter} is being observed.
+   * <p>The callback will be called when the {@link Meter} is being observed.
    *
    * <p>Callbacks are expected to abide by the following restrictions:
    *
@@ -52,4 +52,17 @@ public interface LongCounterBuilder {
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   ObservableLongCounter buildWithCallback(Consumer<ObservableLongMeasurement> callback);
+
+  /**
+   * Build an observer for this instrument to observe values from a {@link BatchCallback}.
+   *
+   * <p>This observer MUST be registered when creating a {@link Meter#batchCallback(Runnable,
+   * ObservableMeasurement, ObservableMeasurement...) batchCallback}, which records to it. Values
+   * observed outside registered callbacks are ignored.
+   *
+   * @return an observable measurement that batch callbacks use to observe values.
+   */
+  default ObservableLongMeasurement buildObserver() {
+    return DefaultMeter.getInstance().counterBuilder("noop").buildObserver();
+  }
 }

api/all/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java

@@ -28,7 +28,7 @@ public interface LongGaugeBuilder {
   /**
    * Builds this asynchronous instrument with the given callback.
    *
-   * <p>The callback will only be called when the {@link Meter} is being observed.
+   * <p>The callback will be called when the {@link Meter} is being observed.
    *
    * <p>Callbacks are expected to abide by the following restrictions:
    *
@@ -40,4 +40,17 @@ public interface LongGaugeBuilder {
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   ObservableLongGauge buildWithCallback(Consumer<ObservableLongMeasurement> callback);
+
+  /**
+   * Build an observer for this instrument to observe values from a {@link BatchCallback}.
+   *
+   * <p>This observer MUST be registered when creating a {@link Meter#batchCallback(Runnable,
+   * ObservableMeasurement, ObservableMeasurement...) batchCallback}, which records to it. Values
+   * observed outside registered callbacks are ignored.
+   *
+   * @return an observable measurement that batch callbacks use to observe values.
+   */
+  default ObservableLongMeasurement buildObserver() {
+    return DefaultMeter.getInstance().gaugeBuilder("noop").ofLongs().buildObserver();
+  }
 }

api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java

@@ -38,7 +38,7 @@ public interface LongUpDownCounterBuilder {
   /**
    * Builds this asynchronous instrument with the given callback.
    *
-   * <p>The callback will only be called when the {@link Meter} is being observed.
+   * <p>The callback will be called when the {@link Meter} is being observed.
    *
    * <p>Callbacks are expected to abide by the following restrictions:
    *
@@ -50,4 +50,17 @@ public interface LongUpDownCounterBuilder {
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   ObservableLongUpDownCounter buildWithCallback(Consumer<ObservableLongMeasurement> callback);
+
+  /**
+   * Build an observer for this instrument to observe values from a {@link BatchCallback}.
+   *
+   * <p>This observer MUST be registered when creating a {@link Meter#batchCallback(Runnable,
+   * ObservableMeasurement, ObservableMeasurement...) batchCallback}, which records to it. Values
+   * observed outside registered callbacks are ignored.
+   *
+   * @return an observable measurement that batch callbacks use to observe values.
+   */
+  default ObservableLongMeasurement buildObserver() {
+    return DefaultMeter.getInstance().upDownCounterBuilder("noop").buildObserver();
+  }
 }

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

@@ -75,4 +75,33 @@ public interface Meter {
    * @return a builder used for configuring how to report gauge measurements on demand.
    */
   DoubleGaugeBuilder gaugeBuilder(String name);
+
+  /**
+   * Constructs a batch callback.
+   *
+   * <p>Batch callbacks allow a single callback to observe measurements for multiple asynchronous
+   * instruments.
+   *
+   * <p>The callback will be called when the {@link Meter} is being observed.
+   *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   *   <li>Only observe values to registered instruments (i.e. {@code observableMeasurement} and
+   *       {@code additionalMeasurements}
+   * </ul>
+   *
+   * @param callback a callback used to observe values on-demand.
+   * @param observableMeasurement Instruments for which the callback may observe values.
+   * @param additionalMeasurements Instruments for which the callback may observe values.
+   */
+  default BatchCallback batchCallback(
+      Runnable callback,
+      ObservableMeasurement observableMeasurement,
+      ObservableMeasurement... additionalMeasurements) {
+    return DefaultMeter.getInstance()
+        .batchCallback(callback, observableMeasurement, additionalMeasurements);
+  }
 }

api/all/src/main/java/io/opentelemetry/api/metrics/ObservableDoubleMeasurement.java

@@ -8,7 +8,7 @@
 import io.opentelemetry.api.common.Attributes;
 
 /** An interface for observing measurements with {@code double} values. */
-public interface ObservableDoubleMeasurement {
+public interface ObservableDoubleMeasurement extends ObservableMeasurement {
 
   /**
    * Records a measurement.

api/all/src/main/java/io/opentelemetry/api/metrics/ObservableLongMeasurement.java

@@ -8,7 +8,7 @@
 import io.opentelemetry.api.common.Attributes;
 
 /** An interface for observing measurements with {@code long} values. */
-public interface ObservableLongMeasurement {
+public interface ObservableLongMeasurement extends ObservableMeasurement {
 
   /**
    * Records a measurement.

api/all/src/main/java/io/opentelemetry/api/metrics/ObservableMeasurement.java

@@ -0,0 +1,14 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.metrics;
+
+/**
+ * Super interface for observing measurements.
+ *
+ * @see ObservableLongMeasurement
+ * @see ObservableDoubleMeasurement
+ */
+public interface ObservableMeasurement {}