open-telemetry
/
opentelemetry-java
mirror of https://github.com/open-telemetry/opentelemetry-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve metrics API javadoc (#4493) 

* Improve metrics API javadoc

* Fix typo

* Switch to Title Case for instrument names

* Add @since annotations
This commit is contained in:
jack-berg 2022-05-27 10:02:02 -05:00 committed by GitHub
parent 88c7233c7e
commit 4a8850cc64
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
33 changed files with 330 additions and 191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
api/all/src/main/java/io/opentelemetry/api/internal/ValidationUtil.java
View File

@ -70,7 +70,7 @@ public final class ValidationUtil {
log(
"Instrument name \""
+ name
+ "\" is invalid, returning noop instrument. Instrument names must consist of 63 or less characters including alphanumeric, _, ., -, and start with a letter."
+ "\" is invalid, returning noop instrument. Instrument names must consist of 63 or fewer characters including alphanumeric, _, ., -, and start with a letter."
+ logSuffix,
Level.WARNING);
return false;
@ -95,7 +95,7 @@ public final class ValidationUtil {
log(
"Unit \""
+ unit
+ "\" is invalid. Instrument unit must be 63 or less ASCII characters."
+ "\" is invalid. Instrument unit must be 63 or fewer ASCII characters."
+ logSuffix,
Level.WARNING);
return false;

2
api/all/src/main/java/io/opentelemetry/api/metrics/BatchCallback.java
View File

@ -8,6 +8,8 @@ package io.opentelemetry.api.metrics;
/**
* A reference to a batch callback registered via {@link Meter#batchCallback(Runnable,
* ObservableMeasurement, ObservableMeasurement...)}.
*
* @since 1.15.0
*/
public interface BatchCallback extends AutoCloseable {

19
api/all/src/main/java/io/opentelemetry/api/metrics/DefaultMeter.java
View File

@ -12,26 +12,9 @@ import java.util.function.Consumer;
import javax.annotation.concurrent.ThreadSafe;
/**
* No-op implementations of {@link Meter}.
* No-op implementation of {@link Meter}.
*
* <p>This implementation should induce as close to zero overhead as possible.
*
* <p>A few notes from the specification on allowed behaviors leading to this design [<a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument">Instrument
* Spec</a>]:
*
* <ul>
* <li>Multiple Instruments with the same name under the same Meter MUST return an error
* <li>Different Meters MUST be treated as separate namespaces
* <li>Implementations MUST NOT require users to repeatedly obtain a Meter again with the same
* name+version+schema_url to pick up configuration changes. This can be achieved either by
* allowing to work with an outdated configuration or by ensuring that new configuration
* applies also to previously returned Meters.
* <li>A MeterProvider could also return a no-op Meter here if application owners configure the
* SDK to suppress telemetry produced by this library
* <li>In case an invalid name (null or empty string) is specified, a working Meter implementation
* MUST be returned as a fallback rather than returning null or throwing an exception,
* </ul>
*/
@ThreadSafe
class DefaultMeter implements Meter {

10
api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounter.java
View File

@ -9,7 +9,11 @@ import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.Context;
import javax.annotation.concurrent.ThreadSafe;
/** A counter instrument that records {@code double} values. */
/**
* A Counter instrument that records {@code double} values.
*
* @since 1.10.0
*/
@ThreadSafe
public interface DoubleCounter {
/**
@ -29,7 +33,7 @@ public interface DoubleCounter {
* measurement.
*
* @param value The increment amount. MUST be non-negative.
* @param attributes A set of attributes to associate with the count.
* @param attributes A set of attributes to associate with the value.
*/
void add(double value, Attributes attributes);
@ -37,7 +41,7 @@ public interface DoubleCounter {
* Records a value with a set of attributes.
*
* @param value The increment amount. MUST be non-negative.
* @param attributes A set of attributes to associate with the count.
* @param attributes A set of attributes to associate with the value.
* @param context The explicit context to associate with this measurement.
*/
void add(double value, Attributes attributes, Context context);

30
api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java
View File

@ -7,45 +7,52 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/** Builder class for {@link DoubleCounter}. */
/**
* Builder class for {@link DoubleCounter}.
*
* @since 1.10.0
*/
public interface DoubleCounterBuilder {
/**
* Sets the description for this instrument.
*
* <p>Description strings should follow the instrument description rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
* @param description The description.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
* Description</a>
*/
DoubleCounterBuilder setDescription(String description);
/**
* Sets the unit of measure for this instrument.
*
* <p>Unit strings should follow the instrument unit rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
* @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
* Unit</a>
*/
DoubleCounterBuilder setUnit(String unit);
/**
* Builds and returns a {@code DoubleCounter} with the desired options.
* Builds and returns a Counter instrument with the configuration.
*
* @return a {@code DoubleCounter} with the desired options.
* @return The Counter instrument.
*/
DoubleCounter build();
/**
* Builds this asynchronous instrument with the given callback.
* Builds an Asynchronous Counter instrument with the given callback.
*
* <p>The callback will be called when the {@link Meter} is being observed.
* <p>The callback will be called when the instrument 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>Return positive, monotonically increasing values.
* </ul>
*
* @param callback A state-capturing callback used to observe values on-demand.
* @param callback A callback which observes measurements when invoked.
*/
ObservableDoubleCounter buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
@ -57,6 +64,7 @@ public interface DoubleCounterBuilder {
* observed outside registered callbacks are ignored.
*
* @return an observable measurement that batch callbacks use to observe values.
* @since 1.15.0
*/
default ObservableDoubleMeasurement buildObserver() {
return DefaultMeter.getInstance().counterBuilder("noop").ofDoubles().buildObserver();

27
api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java
View File

@ -7,31 +7,39 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/** A builder for Gauge metric types. These can only be asynchronously collected. */
/**
* A builder for Gauge metric types. These can only be asynchronously collected.
*
* @since 1.10.0
*/
public interface DoubleGaugeBuilder {
/**
* Sets the description for this instrument.
*
* <p>Description strings should follow the instrument description rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
* @param description The description.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
* Description</a>
*/
DoubleGaugeBuilder setDescription(String description);
/**
* Sets the unit of measure for this instrument.
*
* <p>Unit strings should follow the instrument unit rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
* @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
* Unit</a>
*/
DoubleGaugeBuilder setUnit(String unit);
/** Sets the gauge for recording {@code long} values. */
/** Sets the Gauge for recording {@code long} values. */
LongGaugeBuilder ofLongs();
/**
* Builds this asynchronous instrument with the given callback.
* Builds an Asynchronous Gauge instrument with the given callback.
*
* <p>The callback will be called when the {@link Meter} is being observed.
* <p>The callback will be called when the instrument is being observed.
*
* <p>Callbacks are expected to abide by the following restrictions:
*
@ -40,7 +48,7 @@ public interface DoubleGaugeBuilder {
* <li>Safe to call repeatedly, across multiple threads.
* </ul>
*
* @param callback A state-capturing callback used to observe values on-demand.
* @param callback A callback which observes measurements when invoked.
*/
ObservableDoubleGauge buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
@ -52,6 +60,7 @@ public interface DoubleGaugeBuilder {
* observed outside registered callbacks are ignored.
*
* @return an observable measurement that batch callbacks use to observe values.
* @since 1.15.0
*/
default ObservableDoubleMeasurement buildObserver() {
return DefaultMeter.getInstance().gaugeBuilder("noop").buildObserver();

16
api/all/src/main/java/io/opentelemetry/api/metrics/DoubleHistogram.java
View File

@ -9,7 +9,11 @@ import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.Context;
import javax.annotation.concurrent.ThreadSafe;
/** A histogram instrument that records {@code long} values. */
/**
* A Histogram instrument that records {@code double} values.
*
* @since 1.10.0
*/
@ThreadSafe
public interface DoubleHistogram {
@ -19,7 +23,7 @@ public interface DoubleHistogram {
* <p>Note: This may use {@code Context.current()} to pull the context associated with this
* measurement.
*
* @param value The amount of the measurement.
* @param value The amount of the measurement. MUST be non-negative.
*/
void record(double value);
@ -29,16 +33,16 @@ public interface DoubleHistogram {
* <p>Note: This may use {@code Context.current()} to pull the context associated with this
* measurement.
*
* @param value The amount of the measurement.
* @param attributes A set of attributes to associate with the count.
* @param value The amount of the measurement. MUST be non-negative.
* @param attributes A set of attributes to associate with the value.
*/
void record(double value, Attributes attributes);
/**
* Records a value with a set of attributes.
*
* @param value The amount of the measurement.
* @param attributes A set of attributes to associate with the count.
* @param value The amount of the measurement. MUST be non-negative.
* @param attributes A set of attributes to associate with the value.
* @param context The explicit context to associate with this measurement.
*/
void record(double value, Attributes attributes, Context context);

24
api/all/src/main/java/io/opentelemetry/api/metrics/DoubleHistogramBuilder.java
View File

@ -5,32 +5,40 @@
package io.opentelemetry.api.metrics;
/** Builder class for {@link DoubleHistogram}. */
/**
* Builder class for {@link DoubleHistogram}.
*
* @since 1.10.0
*/
public interface DoubleHistogramBuilder {
/**
* Sets the description for this instrument.
*
* <p>Description strings should follow the instrument description rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
* @param description The description.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
* Description</a>
*/
DoubleHistogramBuilder setDescription(String description);
/**
* Sets the unit of measure for this instrument.
*
* <p>Unit strings should follow the instrument unit rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
* @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
* Unit</a>
*/
DoubleHistogramBuilder setUnit(String unit);
/** Sets the counter for recording {@code long} values. */
/** Sets the Counter for recording {@code long} values. */
LongHistogramBuilder ofLongs();
/**
* Builds and returns a {@code DoubleHistogram} with the desired options.
* Builds and returns a Histogram instrument with the configuration.
*
* @return a {@code DoubleHistogram} with the desired options.
* @return The Histogram instrument.
*/
DoubleHistogram build();
}

10
api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounter.java
View File

@ -9,7 +9,11 @@ import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.Context;
import javax.annotation.concurrent.ThreadSafe;
/** An up-down-counter instrument that records {@code double} values. */
/**
* An UpDownCounter instrument that records {@code double} values.
*
* @since 1.10.0
*/
@ThreadSafe
public interface DoubleUpDownCounter {
/**
@ -29,7 +33,7 @@ public interface DoubleUpDownCounter {
* measurement.
*
* @param value The increment amount. May be positive, negative or zero.
* @param attributes A set of attributes to associate with the count.
* @param attributes A set of attributes to associate with the value.
*/
void add(double value, Attributes attributes);
@ -37,7 +41,7 @@ public interface DoubleUpDownCounter {
* Records a value with a set of attributes.
*
* @param value The increment amount. May be positive, negative or zero.
* @param attributes A set of attributes to associate with the count.
* @param attributes A set of attributes to associate with the value.
* @param context The explicit context to associate with this measurement.
*/
void add(double value, Attributes attributes, Context context);

29
api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java
View File

@ -7,35 +7,43 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/** Builder class for {@link DoubleUpDownCounter}. */
/**
* Builder class for {@link DoubleUpDownCounter}.
*
* @since 1.10.0
*/
public interface DoubleUpDownCounterBuilder {
/**
* Sets the description for this instrument.
*
* <p>Description strings should follow the instrument description rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
* @param description The description.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
* Description</a>
*/
DoubleUpDownCounterBuilder setDescription(String description);
/**
* Sets the unit of measure for this instrument.
*
* <p>Unit strings should follow the instrument unit rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
* @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
* Unit</a>
*/
DoubleUpDownCounterBuilder setUnit(String unit);
/**
* Builds and returns a {@code DoubleUpDownCounter} with the desired options.
* Builds and returns an UpDownCounter instrument with the configuration.
*
* @return a {@code DoubleUpDownCounter} with the desired options.
* @return The UpDownCounter instrument.
*/
DoubleUpDownCounter build();
/**
* Builds this asynchronous instrument with the given callback.
* Builds an Asynchronous UpDownCounter instrument with the given callback.
*
* <p>The callback will be called when the {@link Meter} is being observed.
* <p>The callback will be called when the instrument is being observed.
*
* <p>Callbacks are expected to abide by the following restrictions:
*
@ -44,7 +52,7 @@ public interface DoubleUpDownCounterBuilder {
* <li>Safe to call repeatedly, across multiple threads.
* </ul>
*
* @param callback A state-capturing callback used to observe values on-demand.
* @param callback A callback which observes measurements when invoked.
*/
ObservableDoubleUpDownCounter buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);
@ -56,6 +64,7 @@ public interface DoubleUpDownCounterBuilder {
* observed outside registered callbacks are ignored.
*
* @return an observable measurement that batch callbacks use to observe values.
* @since 1.15.0
*/
default ObservableDoubleMeasurement buildObserver() {
return DefaultMeter.getInstance().upDownCounterBuilder("noop").ofDoubles().buildObserver();

9
api/all/src/main/java/io/opentelemetry/api/metrics/LongCounter.java
View File

@ -10,10 +10,9 @@ import io.opentelemetry.context.Context;
import javax.annotation.concurrent.ThreadSafe;
/**
* A counter instrument that records {@code long} values.
* A Counter instrument that records {@code long} values.
*
* <p>Counters only allow adding positive values, and guarantee the resulting metrics will be
* always-increasing monotonic sums.
* @since 1.10.0
*/
@ThreadSafe
public interface LongCounter {
@ -35,7 +34,7 @@ public interface LongCounter {
* measurement.
*
* @param value The increment amount. MUST be non-negative.
* @param attributes A set of attributes to associate with the count.
* @param attributes A set of attributes to associate with the value.
*/
void add(long value, Attributes attributes);
@ -43,7 +42,7 @@ public interface LongCounter {
* Records a value with a set of attributes.
*
* @param value The increment amount. MUST be non-negative.
* @param attributes A set of attributes to associate with the count.
* @param attributes A set of attributes to associate with the value.
* @param context The explicit context to associate with this measurement.
*/
void add(long value, Attributes attributes, Context context);

32
api/all/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java
View File

@ -7,49 +7,56 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/** Builder class for {@link LongCounter}. */
/**
* Builder class for {@link LongCounter}.
*
* @since 1.10.0
*/
public interface LongCounterBuilder {
/**
* Sets the description for this instrument.
*
* <p>Description strings should follow the instrument description rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
* @param description The description.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
* Description</a>
*/
LongCounterBuilder setDescription(String description);
/**
* Sets the unit of measure for this instrument.
*
* <p>Unit strings should follow the instrument unit rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
* @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
* Unit</a>
*/
LongCounterBuilder setUnit(String unit);
/** Sets the counter for recording {@code double} values. */
/** Sets the Counter for recording {@code double} values. */
DoubleCounterBuilder ofDoubles();
/**
* Builds and returns a {@code LongCounter} with the desired options.
* Builds and returns a Counter instrument with the configuration.
*
* @return a {@code LongCounter} with the desired options.
* @return The Counter instrument.
*/
LongCounter build();
/**
* Builds this asynchronous instrument with the given callback.
* Builds an Asynchronous Counter instrument with the given callback.
*
* <p>The callback will be called when the {@link Meter} is being observed.
* <p>The callback will be called when the instrument 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>Return positive, monotonically increasing values.
* </ul>
*
* @param callback A state-capturing callback used to observe values on-demand.
* @param callback A callback which observes measurements when invoked.
*/
ObservableLongCounter buildWithCallback(Consumer<ObservableLongMeasurement> callback);
@ -61,6 +68,7 @@ public interface LongCounterBuilder {
* observed outside registered callbacks are ignored.
*
* @return an observable measurement that batch callbacks use to observe values.
* @since 1.15.0
*/
default ObservableLongMeasurement buildObserver() {
return DefaultMeter.getInstance().counterBuilder("noop").buildObserver();

25
api/all/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java
View File

@ -7,28 +7,36 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/** A builder for Gauge metric types. These can only be asynchronously collected. */
/**
* A builder for Gauge metric types. These can only be asynchronously collected.
*
* @since 1.10.0
*/
public interface LongGaugeBuilder {
/**
* Sets the description for this instrument.
*
* <p>Description strings should follow the instrument description rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
* @param description The description.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
* Description</a>
*/
LongGaugeBuilder setDescription(String description);
/**
* Sets the unit of measure for this instrument.
*
* <p>Unit strings should follow the instrument unit rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
* @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
* Unit</a>
*/
LongGaugeBuilder setUnit(String unit);
/**
* Builds this asynchronous instrument with the given callback.
* Builds an Asynchronous Gauge instrument with the given callback.
*
* <p>The callback will be called when the {@link Meter} is being observed.
* <p>The callback will be called when the instrument is being observed.
*
* <p>Callbacks are expected to abide by the following restrictions:
*
@ -37,7 +45,7 @@ public interface LongGaugeBuilder {
* <li>Safe to call repeatedly, across multiple threads.
* </ul>
*
* @param callback A state-capturing callback used to observe values on-demand.
* @param callback A callback which observes measurements when invoked.
*/
ObservableLongGauge buildWithCallback(Consumer<ObservableLongMeasurement> callback);
@ -49,6 +57,7 @@ public interface LongGaugeBuilder {
* observed outside registered callbacks are ignored.
*
* @return an observable measurement that batch callbacks use to observe values.
* @since 1.15.0
*/
default ObservableLongMeasurement buildObserver() {
return DefaultMeter.getInstance().gaugeBuilder("noop").ofLongs().buildObserver();

16
api/all/src/main/java/io/opentelemetry/api/metrics/LongHistogram.java
View File

@ -9,7 +9,11 @@ import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.Context;
import javax.annotation.concurrent.ThreadSafe;
/** A histogram instrument that records {@code long} values. */
/**
* A Histogram instrument that records {@code long} values.
*
* @since 1.10.0
*/
@ThreadSafe
public interface LongHistogram {
@ -19,7 +23,7 @@ public interface LongHistogram {
* <p>Note: This may use {@code Context.current()} to pull the context associated with this
* measurement.
*
* @param value The amount of the measurement.
* @param value The amount of the measurement. MUST be non-negative.
*/
void record(long value);
@ -29,16 +33,16 @@ public interface LongHistogram {
* <p>Note: This may use {@code Context.current()} to pull the context associated with this
* measurement.
*
* @param value The amount of the measurement.
* @param attributes A set of attributes to associate with the count.
* @param value The amount of the measurement. MUST be non-negative.
* @param attributes A set of attributes to associate with the value.
*/
void record(long value, Attributes attributes);
/**
* Records a value with a set of attributes.
*
* @param value The amount of the measurement.
* @param attributes A set of attributes to associate with the count.
* @param value The amount of the measurement. MUST be non-negative.
* @param attributes A set of attributes to associate with the value.
* @param context The explicit context to associate with this measurement.
*/
void record(long value, Attributes attributes, Context context);

22
api/all/src/main/java/io/opentelemetry/api/metrics/LongHistogramBuilder.java
View File

@ -5,28 +5,36 @@
package io.opentelemetry.api.metrics;
/** Builder class for {@link LongHistogram}. */
/**
* Builder class for {@link LongHistogram}.
*
* @since 1.10.0
*/
public interface LongHistogramBuilder {
/**
* Sets the description for this instrument.
*
* <p>Description strings should follow the instrument description rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
* @param description The description.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
* Description</a>
*/
LongHistogramBuilder setDescription(String description);
/**
* Sets the unit of measure for this instrument.
*
* <p>Unit strings should follow the instrument unit rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
* @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
* Unit</a>
*/
LongHistogramBuilder setUnit(String unit);
/**
* Builds and returns a {@code LongHistogram} with the desired options.
* Builds and returns a Histogram instrument with the configuration.
*
* @return a {@code LongHistogram} with the desired options.
* @return The Histogram instrument.
*/
LongHistogram build();
}

10
api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounter.java
View File

@ -9,7 +9,11 @@ import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.Context;
import javax.annotation.concurrent.ThreadSafe;
/** An up-down-counter instrument that records {@code long} values. */
/**
* An UpDownCounter instrument that records {@code long} values.
*
* @since 1.10.0
*/
@ThreadSafe
public interface LongUpDownCounter {
/**
@ -29,7 +33,7 @@ public interface LongUpDownCounter {
* measurement.
*
* @param value The increment amount. May be positive, negative or zero.
* @param attributes A set of attributes to associate with the count.
* @param attributes A set of attributes to associate with the value.
*/
void add(long value, Attributes attributes);
@ -37,7 +41,7 @@ public interface LongUpDownCounter {
* Records a value with a set of attributes.
*
* @param value The increment amount. May be positive, negative or zero.
* @param attributes A set of attributes to associate with the count.
* @param attributes A set of attributes to associate with the value.
* @param context The explicit context to associate with this measurement.
*/
void add(long value, Attributes attributes, Context context);

31
api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java
View File

@ -7,38 +7,46 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/** Builder class for {@link LongUpDownCounter}. */
/**
* Builder class for {@link LongUpDownCounter}.
*
* @since 1.10.0
*/
public interface LongUpDownCounterBuilder {
/**
* Sets the description for this instrument.
*
* <p>Description strings should follow the instrument description rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
* @param description The description.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">Instrument
* Description</a>
*/
LongUpDownCounterBuilder setDescription(String description);
/**
* Sets the unit of measure for this instrument.
*
* <p>Unit strings should follow the instrument unit rules:
* https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit
* @param unit The unit. Instrument units must be 63 or fewer ASCII characters.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">Instrument
* Unit</a>
*/
LongUpDownCounterBuilder setUnit(String unit);
/** Sets the counter for recording {@code double} values. */
/** Sets the Counter for recording {@code double} values. */
DoubleUpDownCounterBuilder ofDoubles();
/**
* Builds and returns a {@code LongUpDownCounter} with the desired options.
* Builds and returns an UpDownCounter instrument with the configuration.
*
* @return a {@code LongUpDownCounter} with the desired options.
* @return The UpDownCounter instrument.
*/
LongUpDownCounter build();
/**
* Builds this asynchronous instrument with the given callback.
* Builds an Asynchronous UpDownCounter instrument with the given callback.
*
* <p>The callback will be called when the {@link Meter} is being observed.
* <p>The callback will be called when the instrument is being observed.
*
* <p>Callbacks are expected to abide by the following restrictions:
*
@ -47,7 +55,7 @@ public interface LongUpDownCounterBuilder {
* <li>Safe to call repeatedly, across multiple threads.
* </ul>
*
* @param callback A state-capturing callback used to observe values on-demand.
* @param callback A callback which observes measurements when invoked.
*/
ObservableLongUpDownCounter buildWithCallback(Consumer<ObservableLongMeasurement> callback);
@ -59,6 +67,7 @@ public interface LongUpDownCounterBuilder {
* observed outside registered callbacks are ignored.
*
* @return an observable measurement that batch callbacks use to observe values.
* @since 1.15.0
*/
default ObservableLongMeasurement buildObserver() {
return DefaultMeter.getInstance().upDownCounterBuilder("noop").buildObserver();

104
api/all/src/main/java/io/opentelemetry/api/metrics/Meter.java
View File

@ -8,71 +8,111 @@ package io.opentelemetry.api.metrics;
import javax.annotation.concurrent.ThreadSafe;
/**
* Provides instruments used to produce metrics.
* Provides instruments used to record measurements which are aggregated to metrics.
*
* <p>Instruments are obtained through builders provided by this interface. Each builder has a
* default "type" associated with recordings that may be changed.
*
* <p>A Meter is generally associated with an instrumentation scope, e.g. "I monitor apache
* httpclient".
* default measurement type (long or double) that may be changed.
*
* <p>Choosing an instrument can be hard, but here's a rule of thumb for selecting the right
* instrument:
*
* <ul>
* <li>I want to <b>count</b> something.
* <li>I want to <b>count</b> something (by recording a delta value):
* <ul>
* <li>The value is always increasing / I want to track its <b>rate</b>.<br>
* Use {@link #counterBuilder(String)}
* <li>The value is not always increasing.<br>
* Use {@link #upDownCounterBuilder(String)}
* <li>If the value is monotonically increasing (the delta value is always non-negative) -
* use a Counter:
* <pre>meter.counterBuilder("my-counter").build()</pre>
* <li>If the value is NOT monotonically increasing (the delta value can be positive,
* negative, or zero)) - use an UpDownCounter:
* <pre>meter.upDownCounterBuilder("my-up-down-counter").build()</pre>
* </ul>
* <li>I want to <b>record</b> or <b>time</b> something, and the <b>statistics</b> about this
* thing are likely to be meaningful - use a Histogram:
* <pre>meter.histogramBuilder("my-histogram").build()</pre>
* <li>I want to <b>measure</b> something (by reporting an absolute value):
* <ul>
* <li>If it makes NO sense to add up the values across different sets of attributes, use an
* Asynchronous Gauge:
* <pre>
* meter.gaugeBuilder("my-gauge").buildWithCallback(observableMeasurement -> observableMeasurement.record(..))
* </pre>
* <li>If it makes sense to add up the values across different sets of attributes:
* <ul>
* <li>If the value is monotonically increasing - use an Asynchronous Counter:
* <pre>
* meter.counterBuilder("my-async-counter").buildWithCallback(observableMeasurement -> observableMeasurement.record(..))
* </pre>
* <li>If the value is NOT monotonically increasing - use an Asynchronous
* UpDownCounter:
* <pre>
* meter.upDownCounterBuilder("my-async-counter").buildWithCallback(observableMeasurement -> observableMeasurement.record(..))
* </pre>
* </ul>
* </ul>
* <li>I want to <b>time</b> something, or record measurements where the statistics are important
* (e.g. latency).<br>
* <b>Use {@link #histogramBuilder(String)}</b>
* <li>I want to measure something by sampling a value stored elsewhere. <br>
* Use {@link #gaugeBuilder(String)}
* </ul>
*
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/supplementary-guidelines.md#instrument-selection">Instrument
* Selection Guidelines</a>
* @since 1.10.0
*/
@ThreadSafe
public interface Meter {
/**
* Constructs a counter instrument.
* Constructs a Counter instrument.
*
* <p>This is used to build both synchronous (in-context) instruments and asynchronous (callback)
* instruments.
* <p>This is used to build both synchronous instruments and asynchronous instruments (i.e.
* callbacks).
*
* @param name the name used for the counter.
* @return a builder for configuring a new Counter instrument. Defaults to recording long values,
* but may be changed.
* @param name the name of the Counter. Instrument names must consist of 63 or fewer characters
* including alphanumeric, _, ., -, and start with a letter.
* @return a builder for configuring a Counter instrument. Defaults to recording long values, but
* may be changed.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule">Instrument
* Naming Rule</a>
*/
LongCounterBuilder counterBuilder(String name);
/**
* Constructs an up-down-counter instrument.
* Constructs an UpDownCounter instrument.
*
* <p>This is used to build both synchronous (in-context) instruments and asynchronous (callback)
* instruments.
* <p>This is used to build both synchronous instruments and asynchronous instruments (i.e.
* callbacks).
*
* @param name the name used for the counter.
* @return a builder for configuring a new Counter synchronous instrument. Defaults to recording
* long values, but may be changed.
* @param name the name of the UpDownCounter. Instrument names must consist of 63 or fewer
* characters including alphanumeric, _, ., -, and start with a letter.
* @return a builder for configuring an UpDownCounter instrument. Defaults to recording long
* values, but may be changed.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule">Instrument
* Naming Rule</a>
*/
LongUpDownCounterBuilder upDownCounterBuilder(String name);
/**
* Constructs a Histogram instrument.
*
* @param name the name used for the counter.
* @return a builder for configuring a new Histogram synchronous instrument. Defaults to recording
* @param name the name of the Histogram. Instrument names must consist of 63 or fewer characters
* including alphanumeric, _, ., -, and start with a letter.
* @return a builder for configuring a Histogram synchronous instrument. Defaults to recording
* double values, but may be changed.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule">Instrument
* Naming Rule</a>
*/
DoubleHistogramBuilder histogramBuilder(String name);
/**
* Constructs an asynchronous gauge.
* Constructs an Asynchronous Gauge instrument.
*
* @return a builder used for configuring how to report gauge measurements on demand.
* @param name the name of the Gauge. Instrument names must consist of 63 or fewer characters
* including alphanumeric, _, ., -, and start with a letter.
* @return a builder used for configuring a Gauge instrument. Defaults to recording double values,
* but may be changed.
* @see <a
* href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule">Instrument
* Naming Rule</a>
*/
DoubleGaugeBuilder gaugeBuilder(String name);
@ -82,7 +122,7 @@ public interface Meter {
* <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>The callback will be called when the instruments are being observed.
*
* <p>Callbacks are expected to abide by the following restrictions:
*

5
api/all/src/main/java/io/opentelemetry/api/metrics/MeterBuilder.java
View File

@ -8,16 +8,13 @@ package io.opentelemetry.api.metrics;
/**
* Builder class for creating {@link Meter} instances.
*
* @since 1.4.0
* @since 1.10.0
*/
public interface MeterBuilder {
/**
* Assigns an OpenTelemetry schema URL to the resulting Meter.
*
* <p>Schemas are used to identify expected metrics (semantic conventions) and allow backends to
* "automatically migrate" to supported versions.
*
* @param schemaUrl The URL of the OpenTelemetry schema being used by this instrumentation scope.
* @return this
*/

13
api/all/src/main/java/io/opentelemetry/api/metrics/MeterProvider.java
View File

@ -10,34 +10,31 @@ import javax.annotation.concurrent.ThreadSafe;
/**
* A registry for creating named {@link Meter}s.
*
* <p>A MeterProvider represents a configured (or noop) Metric collection system that can be used to
* instrument code.
*
* <p>The name <i>Provider</i> is for consistency with other languages and it is <b>NOT</b> loaded
* using reflection.
*
* @see io.opentelemetry.api.metrics.Meter
* @see Meter
* @since 1.10.0
*/
@ThreadSafe
public interface MeterProvider {
/**
* Gets or creates a named and versioned meter instance.
* Gets or creates a named Meter instance.
*
* @param instrumentationScopeName A name uniquely identifying the instrumentation scope, such as
* the instrumentation library, package, or fully qualified class name. Must not be null.
* @return a meter instance.
* @return a Meter instance.
*/
default Meter get(String instrumentationScopeName) {
return meterBuilder(instrumentationScopeName).build();
}
/**
* Creates a MeterBuilder for a named meter instance.
* Creates a MeterBuilder for a named Meter instance.
*
* @param instrumentationScopeName A name uniquely identifying the instrumentation scope, such as
* the instrumentation library, package, or fully qualified class name. Must not be null.
* @return a MeterBuilder instance.
* @since 1.4.0
*/
MeterBuilder meterBuilder(String instrumentationScopeName);

8
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableDoubleCounter.java
View File

@ -8,8 +8,10 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/**
* A reference to an observable metric registered with {@link
* A reference to an observable instrument registered with {@link
* DoubleCounterBuilder#buildWithCallback(Consumer)}.
*
* @since 1.10.0
*/
public interface ObservableDoubleCounter extends AutoCloseable {
@ -18,7 +20,9 @@ public interface ObservableDoubleCounter extends AutoCloseable {
* After this is called, the callback won't be invoked on future collections. Subsequent calls to
* {@link #close()} have no effect.
*
* <p>Note: other callbacks registered to the metric with the same identity are unaffected.
* <p>Note: other callbacks registered to the instrument with the same identity are unaffected.
*
* @since 1.12.0
*/
@Override
default void close() {}

8
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableDoubleGauge.java
View File

@ -8,8 +8,10 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/**
* A reference to an observable metric registered with {@link
* A reference to an observable instrument registered with {@link
* DoubleGaugeBuilder#buildWithCallback(Consumer)}.
*
* @since 1.10.0
*/
public interface ObservableDoubleGauge extends AutoCloseable {
@ -18,7 +20,9 @@ public interface ObservableDoubleGauge extends AutoCloseable {
* After this is called, the callback won't be invoked on future collections. Subsequent calls to
* {@link #close()} have no effect.
*
* <p>Note: other callbacks registered to the metric with the same identity are unaffected.
* <p>Note: other callbacks registered to the instrument with the same identity are unaffected.
*
* @since 1.12.0
*/
@Override
default void close() {}

12
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableDoubleMeasurement.java
View File

@ -7,21 +7,25 @@ package io.opentelemetry.api.metrics;
import io.opentelemetry.api.common.Attributes;
/** An interface for observing measurements with {@code double} values. */
/**
* An interface for observing measurements with {@code double} values.
*
* @since 1.10.0
*/
public interface ObservableDoubleMeasurement extends ObservableMeasurement {
/**
* Records a measurement.
*
* @param value The measurement amount.
* @param value The measurement value.
*/
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.
* @param value The measurement value.
* @param attributes A set of attributes to associate with the value.
*/
void record(double value, Attributes attributes);
}

8
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableDoubleUpDownCounter.java
View File

@ -8,8 +8,10 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/**
* A reference to an observable metric registered with {@link
* A reference to an observable instrument registered with {@link
* DoubleUpDownCounterBuilder#buildWithCallback(Consumer)}.
*
* @since 1.10.0
*/
public interface ObservableDoubleUpDownCounter extends AutoCloseable {
@ -18,7 +20,9 @@ public interface ObservableDoubleUpDownCounter extends AutoCloseable {
* DoubleUpDownCounterBuilder#buildWithCallback(Consumer)}. After this is called, the callback
* won't be invoked on future collections. Subsequent calls to {@link #close()} have no effect.
*
* <p>Note: other callbacks registered to the metric with the same identity are unaffected.
* <p>Note: other callbacks registered to the instrument with the same identity are unaffected.
*
* @since 1.12.0
*/
@Override
default void close() {}

8
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableLongCounter.java
View File

@ -8,8 +8,10 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/**
* A reference to an observable metric registered with {@link
* A reference to an observable instrument registered with {@link
* LongCounterBuilder#buildWithCallback(Consumer)}.
*
* @since 1.10.0
*/
public interface ObservableLongCounter extends AutoCloseable {
@ -18,7 +20,9 @@ public interface ObservableLongCounter extends AutoCloseable {
* After this is called, the callback won't be invoked on future collections. Subsequent calls to
* {@link #close()} have no effect.
*
* <p>Note: other callbacks registered to the metric with the same identity are unaffected.
* <p>Note: other callbacks registered to the instrument with the same identity are unaffected.
*
* @since 1.12.0
*/
@Override
default void close() {}

8
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableLongGauge.java
View File

@ -8,8 +8,10 @@ package io.opentelemetry.api.metrics;
import java.util.function.Consumer;
/**
* A reference to an observable metric registered with {@link
* A reference to an observable instrument registered with {@link
* LongGaugeBuilder#buildWithCallback(Consumer)}.
*
* @since 1.10.0
*/
public interface ObservableLongGauge extends AutoCloseable {
@ -18,7 +20,9 @@ public interface ObservableLongGauge extends AutoCloseable {
* this is called, the callback won't be invoked on future collections. Subsequent calls to {@link
* #close()} have no effect.
*
* <p>Note: other callbacks registered to the metric with the same identity are unaffected.
* <p>Note: other callbacks registered to the instrument with the same identity are unaffected.
*
* @since 1.12.0
*/
@Override
default void close() {}

12
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableLongMeasurement.java
View File

@ -7,21 +7,25 @@ package io.opentelemetry.api.metrics;
import io.opentelemetry.api.common.Attributes;
/** An interface for observing measurements with {@code long} values. */
/**
* An interface for observing measurements with {@code long} values.
*
* @since 1.10.0
*/
public interface ObservableLongMeasurement extends ObservableMeasurement {
/**
* Records a measurement.
*
* @param value The measurement amount.
* @param value The measurement value.
*/
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.
* @param value The measurement value.
* @param attributes A set of attributes to associate with the value.
*/
void record(long value, Attributes attributes);
}

4
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableLongUpDownCounter.java
View File

@ -10,6 +10,8 @@ import java.util.function.Consumer;
/**
* A reference to an observable metric registered with {@link
* LongUpDownCounterBuilder#buildWithCallback(Consumer)}.
*
* @since 1.10.0
*/
public interface ObservableLongUpDownCounter extends AutoCloseable {
@ -19,6 +21,8 @@ public interface ObservableLongUpDownCounter extends AutoCloseable {
* be invoked on future collections. Subsequent calls to {@link #close()} have no effect.
*
* <p>Note: other callbacks registered to the metric with the same identity are unaffected.
*
* @since 1.12.0
*/
@Override
default void close() {}

1
api/all/src/main/java/io/opentelemetry/api/metrics/ObservableMeasurement.java
View File

@ -10,5 +10,6 @@ package io.opentelemetry.api.metrics;
*
* @see ObservableLongMeasurement
* @see ObservableDoubleMeasurement
* @since 1.15.0
*/
public interface ObservableMeasurement {}

2
api/all/src/main/java/io/opentelemetry/api/trace/DefaultTracer.java
View File

@ -13,7 +13,7 @@ import java.util.concurrent.TimeUnit;
import javax.annotation.Nullable;
import javax.annotation.concurrent.ThreadSafe;
/** No-op implementations of {@link Tracer}. */
/** No-op implementation of {@link Tracer}. */
@ThreadSafe
final class DefaultTracer implements Tracer {

4
api/all/src/test/java/io/opentelemetry/api/internal/ValidationUtilTest.java
View File

@ -23,7 +23,7 @@ public class ValidationUtilTest {
void checkValidInstrumentName_InvalidNameLogs() {
assertThat(ValidationUtil.checkValidInstrumentName("1", " suffix")).isFalse();
apiUsageLogs.assertContains(
"Instrument name \"1\" is invalid, returning noop instrument. Instrument names must consist of 63 or less characters including alphanumeric, _, ., -, and start with a letter. suffix");
"Instrument name \"1\" is invalid, returning noop instrument. Instrument names must consist of 63 or fewer characters including alphanumeric, _, ., -, and start with a letter. suffix");
}
@Test
@ -79,7 +79,7 @@ public class ValidationUtilTest {
void checkValidInstrumentUnit_InvalidUnitLogs() {
assertThat(ValidationUtil.checkValidInstrumentUnit("日", " suffix")).isFalse();
apiUsageLogs.assertContains(
"Unit \"日\" is invalid. Instrument unit must be 63 or less ASCII characters." + " suffix");
"Unit \"日\" is invalid. Instrument unit must be 63 or fewer ASCII characters." + " suffix");
}
@Test

4
api/all/src/test/java/io/opentelemetry/api/metrics/DefaultMeterTest.java
View File

@ -71,7 +71,7 @@ public class DefaultMeterTest {
.allMatch(
log ->
log.equals(
"Instrument name \"1\" is invalid, returning noop instrument. Instrument names must consist of 63 or less characters including alphanumeric, _, ., -, and start with a letter."));
"Instrument name \"1\" is invalid, returning noop instrument. Instrument names must consist of 63 or fewer characters including alphanumeric, _, ., -, and start with a letter."));
}
@Test
@ -107,7 +107,7 @@ public class DefaultMeterTest {
.allMatch(
log ->
log.equals(
"Unit \"日\" is invalid. Instrument unit must be 63 or less ASCII characters."));
"Unit \"日\" is invalid. Instrument unit must be 63 or fewer ASCII characters."));
}
@Test

4
sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkMeterTest.java
View File

@ -95,7 +95,7 @@ class SdkMeterTest {
.allMatch(
log ->
log.equals(
"Instrument name \"1\" is invalid, returning noop instrument. Instrument names must consist of 63 or less characters including alphanumeric, _, ., -, and start with a letter. Returning noop instrument."));
"Instrument name \"1\" is invalid, returning noop instrument. Instrument names must consist of 63 or fewer characters including alphanumeric, _, ., -, and start with a letter. Returning noop instrument."));
}
@Test
@ -135,7 +135,7 @@ class SdkMeterTest {
.allMatch(
log ->
log.equals(
"Unit \"日\" is invalid. Instrument unit must be 63 or less ASCII characters. Using \"\" for instrument my-instrument instead."));
"Unit \"日\" is invalid. Instrument unit must be 63 or fewer ASCII characters. Using \"\" for instrument my-instrument instead."));
}
@Test