Package io.opentelemetry.api.metrics

Interface Meter

@ThreadSafe public interface 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(..))
Since:
1.10.0
See Also:

  • Method Details

    • counterBuilder

      LongCounterBuilder counterBuilder(String name)
      Constructs a Counter instrument.

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

      Parameters:
      name - the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, and start with a letter.
      Returns:
      a builder for configuring a Counter instrument. Defaults to recording long values, but may be changed.
      See Also:

    • upDownCounterBuilder

      LongUpDownCounterBuilder upDownCounterBuilder(String name)
      Constructs an UpDownCounter instrument.

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

      Parameters:
      name - the name of the UpDownCounter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, ., -, and start with a letter.
      Returns:
      a builder for configuring an UpDownCounter instrument. Defaults to recording long values, but may be changed.
      See Also:

    • histogramBuilder

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

    • gaugeBuilder

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

    • batchCallback

      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 - a callback used to observe values on-demand.
      observableMeasurement - Instruments for which the callback may observe values.
      additionalMeasurements - Instruments for which the callback may observe values.
      Since:
      1.15.0