OpenTelemetry Java 1.49.0 · io.opentelemetry.api.metrics.Meter

Provides instruments used to record measurements which are aggregated to metrics.

Instruments are obtained through builders provided by this interface. Each builder has a default measurement type (long or double) that may be changed.

Choosing an instrument can be hard, but here's a rule of thumb for selecting the right instrument:

I want to count something (by recording a delta value):
- If the value is monotonically increasing (the delta value is always non-negative) - use a Counter:
```
meter.counterBuilder("my-counter").build()
```
- If the value is NOT monotonically increasing (the delta value can be positive, negative, or zero)) - use an UpDownCounter:
```
meter.upDownCounterBuilder("my-up-down-counter").build()
```
I want to record or time something, and the statistics about this thing are likely to be meaningful - use a Histogram:
```
meter.histogramBuilder("my-histogram").build()
```

I want to measure something (by reporting an absolute value):

If it makes NO sense to add up the values across different sets of attributes, use an Asynchronous Gauge:

            meter.gaugeBuilder("my-gauge").buildWithCallback(observableMeasurement -> observableMeasurement.record(..))

If it makes sense to add up the values across different sets of attributes:

If the value is monotonically increasing - use an Asynchronous Counter:

                  meter.counterBuilder("my-async-counter").buildWithCallback(observableMeasurement -> observableMeasurement.record(..))

If the value is NOT monotonically increasing - use an Asynchronous UpDownCounter:

                  meter.upDownCounterBuilder("my-async-counter").buildWithCallback(observableMeasurement -> observableMeasurement.record(..))

Method Summary

Modifier and Type	Method and Description
public default BatchCallback	batchCallback(Runnable a callback used to observe values on-demand. callback, ObservableMeasurement Instruments for which the callback may observe values. observableMeasurement, ObservableMeasurement... Instruments for which the callback may observe values. additionalMeasurements) Constructs a batch callback.
public LongCounterBuilder	Returns: a builder for configuring a Counter instrument. Defaults to recording long values, but may be changed. counterBuilder(String the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter. name) Constructs a Counter instrument.
public DoubleGaugeBuilder	Returns: a builder used for configuring a Gauge instrument. Defaults to recording double values, but may be changed. gaugeBuilder(String the name of the Gauge. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter. name) Constructs an Asynchronous Gauge instrument.
public DoubleHistogramBuilder	Returns: a builder for configuring a Histogram synchronous instrument. Defaults to recording double values, but may be changed. histogramBuilder(String the name of the Histogram. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter. name) Constructs a Histogram instrument.
public LongUpDownCounterBuilder	Returns: a builder for configuring an UpDownCounter instrument. Defaults to recording long values, but may be changed. upDownCounterBuilder(String the name of the UpDownCounter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter. name) Constructs an UpDownCounter instrument.

Method Detail

batchCallback back to summary

batchCallback	back to summary
public default BatchCallback batchCallback(Runnable callback, ObservableMeasurement observableMeasurement, ObservableMeasurement... additionalMeasurements) Constructs a batch callback. Batch callbacks allow a single callback to observe measurements for multiple asynchronous instruments. The callback will be called when the instruments are being observed. 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. `observableMeasurement` and `additionalMeasurements` Parameters callback:Runnable a callback used to observe values on-demand. observableMeasurement:ObservableMeasurement Instruments for which the callback may observe values. additionalMeasurements:ObservableMeasurement[] Instruments for which the callback may observe values. Since 1.15.0

public default BatchCallback batchCallback(Runnable callback, ObservableMeasurement observableMeasurement, ObservableMeasurement... additionalMeasurements)

Constructs a batch callback.

Batch callbacks allow a single callback to observe measurements for multiple asynchronous instruments.

The callback will be called when the instruments are being observed.

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. observableMeasurement and additionalMeasurements

Parameters

callback:Runnable: a callback used to observe values on-demand.
observableMeasurement:ObservableMeasurement: Instruments for which the callback may observe values.
additionalMeasurements:ObservableMeasurement[]: Instruments for which the callback may observe values.

Since

1.15.0

counterBuilder	back to summary
public LongCounterBuilder counterBuilder(String name) Constructs a Counter instrument. This is used to build both synchronous instruments and asynchronous instruments (i.e. callbacks). Parameters name:String the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter. Returns:LongCounterBuilder a builder for configuring a Counter instrument. Defaults to recording long values, but may be changed. See Also Instrument Naming Rule

counterBuilder

back to summary

public LongCounterBuilder counterBuilder(String name)

Constructs a Counter instrument.

This is used to build both synchronous instruments and asynchronous instruments (i.e. callbacks).

Parameters

name:String: the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter.

Returns:LongCounterBuilder

a builder for configuring a Counter instrument. Defaults to recording long values, but may be changed.

See Also

Instrument Naming Rule

gaugeBuilder	back to summary
public DoubleGaugeBuilder gaugeBuilder(String name) Constructs an Asynchronous Gauge instrument. Parameters name:String the name of the Gauge. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter. Returns:DoubleGaugeBuilder a builder used for configuring a Gauge instrument. Defaults to recording double values, but may be changed. See Also Instrument Naming Rule

gaugeBuilder

back to summary

public DoubleGaugeBuilder gaugeBuilder(String name)

Constructs an Asynchronous Gauge instrument.

Parameters

name:String: the name of the Gauge. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter.

Returns:DoubleGaugeBuilder

a builder used for configuring a Gauge instrument. Defaults to recording double values, but may be changed.

See Also

Instrument Naming Rule

histogramBuilder	back to summary
public DoubleHistogramBuilder histogramBuilder(String name) Constructs a Histogram instrument. Parameters name:String the name of the Histogram. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter. Returns:DoubleHistogramBuilder a builder for configuring a Histogram synchronous instrument. Defaults to recording double values, but may be changed. See Also Instrument Naming Rule

histogramBuilder

back to summary

public DoubleHistogramBuilder histogramBuilder(String name)

Constructs a Histogram instrument.

Parameters

name:String: the name of the Histogram. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter.

Returns:DoubleHistogramBuilder

a builder for configuring a Histogram synchronous instrument. Defaults to recording double values, but may be changed.

See Also

Instrument Naming Rule

upDownCounterBuilder	back to summary
public LongUpDownCounterBuilder upDownCounterBuilder(String name) Constructs an UpDownCounter instrument. This is used to build both synchronous instruments and asynchronous instruments (i.e. callbacks). Parameters name:String the name of the UpDownCounter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter. Returns:LongUpDownCounterBuilder a builder for configuring an UpDownCounter instrument. Defaults to recording long values, but may be changed. See Also Instrument Naming Rule

upDownCounterBuilder

back to summary

public LongUpDownCounterBuilder upDownCounterBuilder(String name)

Constructs an UpDownCounter instrument.

This is used to build both synchronous instruments and asynchronous instruments (i.e. callbacks).

Parameters

name:String: the name of the UpDownCounter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, /, and start with a letter.

Returns:LongUpDownCounterBuilder

a builder for configuring an UpDownCounter instrument. Defaults to recording long values, but may be changed.

See Also

Instrument Naming Rule

public Interface Meter

Method Summary

Method Detail