org.apache.rocketmq.shaded.io.opentelemetry.api.metrics.Meter Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of rocketmq-client-java
There is a newer version: 5.0.7
/*
 * Copyright The OpenTelemetry Authors
 * SPDX-License-Identifier: Apache-2.0
 */

package org.apache.rocketmq.shaded.io.opentelemetry.api.metrics;

import javax.annotation.concurrent.ThreadSafe;

/**
 * Provides instruments used to produce metrics.
 *
 * Instruments are obtained through builders provided by this interface. Each builder has a
 * default "type" associated with recordings that may be changed.
 *
 * 
A Meter is generally associated with an instrumentation scope, e.g. "I monitor apache
 * httpclient".
 *
 * 
Choosing an instrument can be hard, but here's a rule of thumb for selecting the right
 * instrument:
 *
 * 

 *   I want to count something.
 *       
 *         The value is always increasing / I want to track its rate.

 *             Use {@link #counterBuilder(String)}
 *         
The value is not always increasing.

 *             Use {@link #upDownCounterBuilder(String)}
 *       
 *   
I want to time something, or record measurements where the statistics are important
 *       (e.g. latency).

 *       Use {@link #histogramBuilder(String)}
 *   
I want to measure something by sampling a value stored elsewhere. 

 *       Use {@link #gaugeBuilder(String)}
 * 
 */
@ThreadSafe
public interface Meter {
  /**
   * Constructs a counter instrument.
   *
   * This is used to build both synchronous (in-context) instruments and asynchronous (callback)
   * instruments.
   *
   * @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.
   */
  LongCounterBuilder counterBuilder(String name);

  /**
   * Constructs an up-down-counter instrument.
   *
   * This is used to build both synchronous (in-context) instruments and asynchronous (callback)
   * instruments.
   *
   * @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.
   */
  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
   *     double values, but may be changed.
   */
  DoubleHistogramBuilder histogramBuilder(String name);

  /**
   * Constructs an asynchronous gauge.
   *
   * @return a builder used for configuring how to report gauge measurements on demand.
   */
  DoubleGaugeBuilder gaugeBuilder(String name);
}