DoubleHistogram.java

/*
 * Copyright The OpenTelemetry Authors
 * SPDX-License-Identifier: Apache-2.0
 */

package io.opentelemetry.api.metrics;

import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.Context;
import javax.annotation.concurrent.ThreadSafe;

/**
 * A Histogram instrument that records {@code double} values.
 *
 * @since 1.10.0
 */
@ThreadSafe
public interface DoubleHistogram {

  /**
   * Records a value.
   *
   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
   * measurement.
   *
   * @param value The amount of the measurement. MUST be non-negative.
   */
  void record(double value);

  /**
   * Records a value with a set of attributes.
   *
   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
   * measurement.
   *
   * @param value The amount of the measurement. MUST be non-negative.
   * @param attributes A set of attributes to associate with the value.
   */
  void record(double value, Attributes attributes);

  /**
   * Records a value with a set of attributes.
   *
   * @param value The amount of the measurement. MUST be non-negative.
   * @param attributes A set of attributes to associate with the value.
   * @param context The explicit context to associate with this measurement.
   */
  void record(double value, Attributes attributes, Context context);

  /**
   * Finish the instrument record.
   *
   * @param attributes A set of attributes to identify the instrument.
   * @since 1.56.0
   */
  default void finish(Attributes attributes) {
    finish(attributes, Context.current());
  }

  /**
   * Finish the instrument record.
   *
   * @param attributes A set of attributes to identify the instrument.
   * @param context The explicit context to associate with this measurement.
   * @since 1.56.0
   */
  default void finish(Attributes attributes, Context context) {}
}