com.aliyun.oss.shade.io.opentelemetry.api.metrics.Meter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of aliyun-sdk-oss-shade Show documentation
The Aliyun OSS SDK for Java used for accessing Aliyun Object Storage Service, includes all service and dependent JARs.
The newest version!
/*
 * Copyright The OpenTelemetry Authors
 * SPDX-License-Identifier: Apache-2.0
 */

package io.opentelemetry.api.metrics;

import javax.annotation.concurrent.ThreadSafe;

/**
 * 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(..))
 *                   
 *             
 *       
 * 
 *
 * @see Instrument
 *     Selection Guidelines
 * @since 1.10.0
 */
@ThreadSafe
public interface Meter {
  /**
   * Constructs a Counter instrument.
   *
   * This is used to build both synchronous instruments and asynchronous instruments (i.e.
   * callbacks).
   *
   * @param name the name of the Counter. Instrument names must consist of 255 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 Instrument
   *     Naming Rule
   */
  LongCounterBuilder counterBuilder(String name);

  /**
   * Constructs an UpDownCounter instrument.
   *
   * 
This is used to build both synchronous instruments and asynchronous instruments (i.e.
   * callbacks).
   *
   * @param name the name of the UpDownCounter. Instrument names must consist of 255 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 Instrument
   *     Naming Rule
   */
  LongUpDownCounterBuilder upDownCounterBuilder(String name);

  /**
   * Constructs a Histogram instrument.
   *
   * @param name the name of the Histogram. Instrument names must consist of 255 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 Instrument
   *     Naming Rule
   */
  DoubleHistogramBuilder histogramBuilder(String name);

  /**
   * Constructs an Asynchronous Gauge instrument.
   *
   * @param name the name of the Gauge. Instrument names must consist of 255 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 Instrument
   *     Naming Rule
   */
  DoubleGaugeBuilder gaugeBuilder(String name);

  /**
   * 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. {@code observableMeasurement} and
   *       {@code additionalMeasurements}
   * 
   *
   * @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.
   * @since 1.15.0
   */
  default BatchCallback batchCallback(
      Runnable callback,
      ObservableMeasurement observableMeasurement,
      ObservableMeasurement... additionalMeasurements) {
    return DefaultMeter.getInstance()
        .batchCallback(callback, observableMeasurement, additionalMeasurements);
  }
}