diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java b/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java index 3ba58c81536..37eb2ee66ae 100644 --- a/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java +++ b/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java @@ -5,6 +5,7 @@ package io.opentelemetry.api.metrics; +import java.util.function.BiConsumer; import java.util.function.Consumer; /** @@ -56,6 +57,34 @@ public interface DoubleCounterBuilder { */ ObservableDoubleCounter buildWithCallback(Consumer callback); + /** + * Builds an Asynchronous Counter instrument with the given callback. + * + *

The callback will be called when the instrument is being observed, with {@code obj} passed + * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling + * automatic cleanup when the measured object is garbage collected. + * + *

The {@code obj} should be an independently-rooted object that the application holds for its + * own purposes (e.g. a connection pool, service instance, or cache). When the application drops + * its strong reference to {@code obj}, the SDK may automatically remove the callback. + * + *

Callbacks are expected to abide by the following restrictions: + * + *

+ * + * @param obj The measured object. The callback receives this as its first argument. + * @param callback A callback which observes measurements when invoked. + * @param The type of the measured object. + */ + @SuppressWarnings("InconsistentOverloads") + default ObservableDoubleCounter buildWithCallback( + T obj, BiConsumer callback) { + return buildWithCallback(measurement -> callback.accept(obj, measurement)); + } + /** * Build an observer for this instrument to observe values from a {@link BatchCallback}. * diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java b/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java index b0ea8b939fa..7b725802583 100644 --- a/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java +++ b/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java @@ -5,6 +5,7 @@ package io.opentelemetry.api.metrics; +import java.util.function.BiConsumer; import java.util.function.Consumer; /** @@ -52,6 +53,34 @@ public interface DoubleGaugeBuilder { */ ObservableDoubleGauge buildWithCallback(Consumer callback); + /** + * Builds an Asynchronous Gauge instrument with the given callback. + * + *

The callback will be called when the instrument is being observed, with {@code obj} passed + * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling + * automatic cleanup when the measured object is garbage collected. + * + *

The {@code obj} should be an independently-rooted object that the application holds for its + * own purposes (e.g. a connection pool, service instance, or cache). When the application drops + * its strong reference to {@code obj}, the SDK may automatically remove the callback. + * + *

Callbacks are expected to abide by the following restrictions: + * + *

    + *
  • Run in a finite amount of time. + *
  • Safe to call repeatedly, across multiple threads. + *
+ * + * @param obj The measured object. The callback receives this as its first argument. + * @param callback A callback which observes measurements when invoked. + * @param The type of the measured object. + */ + @SuppressWarnings("InconsistentOverloads") + default ObservableDoubleGauge buildWithCallback( + T obj, BiConsumer callback) { + return buildWithCallback(measurement -> callback.accept(obj, measurement)); + } + /** * Build an observer for this instrument to observe values from a {@link BatchCallback}. * diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java b/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java index 360aeb19f43..b6c9081ee06 100644 --- a/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java +++ b/api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java @@ -5,6 +5,7 @@ package io.opentelemetry.api.metrics; +import java.util.function.BiConsumer; import java.util.function.Consumer; /** @@ -56,6 +57,34 @@ public interface DoubleUpDownCounterBuilder { */ ObservableDoubleUpDownCounter buildWithCallback(Consumer callback); + /** + * Builds an Asynchronous UpDownCounter instrument with the given callback. + * + *

The callback will be called when the instrument is being observed, with {@code obj} passed + * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling + * automatic cleanup when the measured object is garbage collected. + * + *

The {@code obj} should be an independently-rooted object that the application holds for its + * own purposes (e.g. a connection pool, service instance, or cache). When the application drops + * its strong reference to {@code obj}, the SDK may automatically remove the callback. + * + *

Callbacks are expected to abide by the following restrictions: + * + *

    + *
  • Run in a finite amount of time. + *
  • Safe to call repeatedly, across multiple threads. + *
+ * + * @param obj The measured object. The callback receives this as its first argument. + * @param callback A callback which observes measurements when invoked. + * @param The type of the measured object. + */ + @SuppressWarnings("InconsistentOverloads") + default ObservableDoubleUpDownCounter buildWithCallback( + T obj, BiConsumer callback) { + return buildWithCallback(measurement -> callback.accept(obj, measurement)); + } + /** * Build an observer for this instrument to observe values from a {@link BatchCallback}. * diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java b/api/all/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java index 00ff9f84df1..3f024ebab46 100644 --- a/api/all/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java +++ b/api/all/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java @@ -5,6 +5,7 @@ package io.opentelemetry.api.metrics; +import java.util.function.BiConsumer; import java.util.function.Consumer; /** @@ -60,6 +61,34 @@ public interface LongCounterBuilder { */ ObservableLongCounter buildWithCallback(Consumer callback); + /** + * Builds an Asynchronous Counter instrument with the given callback. + * + *

The callback will be called when the instrument is being observed, with {@code obj} passed + * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling + * automatic cleanup when the measured object is garbage collected. + * + *

The {@code obj} should be an independently-rooted object that the application holds for its + * own purposes (e.g. a connection pool, service instance, or cache). When the application drops + * its strong reference to {@code obj}, the SDK may automatically remove the callback. + * + *

Callbacks are expected to abide by the following restrictions: + * + *

    + *
  • Run in a finite amount of time. + *
  • Safe to call repeatedly, across multiple threads. + *
+ * + * @param obj The measured object. The callback receives this as its first argument. + * @param callback A callback which observes measurements when invoked. + * @param The type of the measured object. + */ + @SuppressWarnings("InconsistentOverloads") + default ObservableLongCounter buildWithCallback( + T obj, BiConsumer callback) { + return buildWithCallback(measurement -> callback.accept(obj, measurement)); + } + /** * Build an observer for this instrument to observe values from a {@link BatchCallback}. * diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java b/api/all/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java index f33c53155e7..d14a7212af1 100644 --- a/api/all/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java +++ b/api/all/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java @@ -5,6 +5,7 @@ package io.opentelemetry.api.metrics; +import java.util.function.BiConsumer; import java.util.function.Consumer; /** @@ -49,6 +50,34 @@ public interface LongGaugeBuilder { */ ObservableLongGauge buildWithCallback(Consumer callback); + /** + * Builds an Asynchronous Gauge instrument with the given callback. + * + *

The callback will be called when the instrument is being observed, with {@code obj} passed + * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling + * automatic cleanup when the measured object is garbage collected. + * + *

The {@code obj} should be an independently-rooted object that the application holds for its + * own purposes (e.g. a connection pool, service instance, or cache). When the application drops + * its strong reference to {@code obj}, the SDK may automatically remove the callback. + * + *

Callbacks are expected to abide by the following restrictions: + * + *

    + *
  • Run in a finite amount of time. + *
  • Safe to call repeatedly, across multiple threads. + *
+ * + * @param obj The measured object. The callback receives this as its first argument. + * @param callback A callback which observes measurements when invoked. + * @param The type of the measured object. + */ + @SuppressWarnings("InconsistentOverloads") + default ObservableLongGauge buildWithCallback( + T obj, BiConsumer callback) { + return buildWithCallback(measurement -> callback.accept(obj, measurement)); + } + /** * Build an observer for this instrument to observe values from a {@link BatchCallback}. * diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java b/api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java index d59ff9789ac..fc73d985566 100644 --- a/api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java +++ b/api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java @@ -5,6 +5,7 @@ package io.opentelemetry.api.metrics; +import java.util.function.BiConsumer; import java.util.function.Consumer; /** @@ -59,6 +60,34 @@ public interface LongUpDownCounterBuilder { */ ObservableLongUpDownCounter buildWithCallback(Consumer callback); + /** + * Builds an Asynchronous UpDownCounter instrument with the given callback. + * + *

The callback will be called when the instrument is being observed, with {@code obj} passed + * as the first argument. This allows the SDK to hold a weak reference to {@code obj}, enabling + * automatic cleanup when the measured object is garbage collected. + * + *

The {@code obj} should be an independently-rooted object that the application holds for its + * own purposes (e.g. a connection pool, service instance, or cache). When the application drops + * its strong reference to {@code obj}, the SDK may automatically remove the callback. + * + *

Callbacks are expected to abide by the following restrictions: + * + *

    + *
  • Run in a finite amount of time. + *
  • Safe to call repeatedly, across multiple threads. + *
+ * + * @param obj The measured object. The callback receives this as its first argument. + * @param callback A callback which observes measurements when invoked. + * @param The type of the measured object. + */ + @SuppressWarnings("InconsistentOverloads") + default ObservableLongUpDownCounter buildWithCallback( + T obj, BiConsumer callback) { + return buildWithCallback(measurement -> callback.accept(obj, measurement)); + } + /** * Build an observer for this instrument to observe values from a {@link BatchCallback}. * diff --git a/api/all/src/main/java/io/opentelemetry/api/metrics/Meter.java b/api/all/src/main/java/io/opentelemetry/api/metrics/Meter.java index d8566457d4c..d296799d40a 100644 --- a/api/all/src/main/java/io/opentelemetry/api/metrics/Meter.java +++ b/api/all/src/main/java/io/opentelemetry/api/metrics/Meter.java @@ -5,6 +5,7 @@ package io.opentelemetry.api.metrics; +import java.util.function.Consumer; import javax.annotation.concurrent.ThreadSafe; /** @@ -145,4 +146,39 @@ default BatchCallback batchCallback( return DefaultMeter.getInstance() .batchCallback(callback, observableMeasurement, additionalMeasurements); } + + /** + * Creates a batch callback with the given measured object. + * + *

The callback will be called when the instruments are being observed, with {@code obj} passed + * as the argument. This allows the SDK to hold a weak reference to {@code obj}, enabling + * automatic cleanup when the measured object is garbage collected. + * + *

The {@code obj} should be an independently-rooted object that the application holds for its + * own purposes (e.g. a connection pool, service instance, or cache). When the application drops + * its strong reference to {@code obj}, the SDK may automatically remove the callback. + * + *

Callbacks are expected to abide by the following restrictions: + * + *

    + *
  • Run in a finite amount of time. + *
  • Safe to call repeatedly, across multiple threads. + *
  • Only observe values to registered instruments (i.e. {@code observableMeasurement} and + * {@code additionalMeasurements} + *
+ * + * @param obj The measured object. The callback receives this as its argument. + * @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. + * @param The type of the measured object. + */ + @SuppressWarnings("InconsistentOverloads") + default BatchCallback batchCallback( + T obj, + Consumer callback, + ObservableMeasurement observableMeasurement, + ObservableMeasurement... additionalMeasurements) { + return batchCallback(() -> callback.accept(obj), observableMeasurement, additionalMeasurements); + } }