Interface Meter

  • All Known Implementing Classes:
    DefaultMeter, ExtendedDefaultMeter, SdkMeter

    @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:
    Instrument Selection Guidelines
    • Method Detail

      • counterBuilder

        LongCounterBuilder counterBuilder​(java.lang.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:
        Instrument Naming Rule
      • upDownCounterBuilder

        LongUpDownCounterBuilder upDownCounterBuilder​(java.lang.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:
        Instrument Naming Rule
      • histogramBuilder

        DoubleHistogramBuilder histogramBuilder​(java.lang.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:
        Instrument Naming Rule
      • gaugeBuilder

        DoubleGaugeBuilder gaugeBuilder​(java.lang.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:
        Instrument Naming Rule
      • batchCallback

        default BatchCallback batchCallback​(java.lang.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