Take a pass at fixing metrics API javadoc issues/missing information. (#3874)

* Take a pass at fixing metrics API javadoc issues/missing information.

* Spotless fix.

api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleCounter.java

@@ -33,7 +33,7 @@ public interface BoundDoubleCounter {
    * Unbinds the current bound instance from the {@link DoubleCounter}.
    *
    * <p>After this method returns the current instance is considered invalid (not being managed by
-   * the instrument).
+   * the instrument). This frees any reserved memory.
    */
   void unbind();
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleHistogram.java

@@ -33,7 +33,7 @@ public interface BoundDoubleHistogram {
    * Unbinds the current bound instance from the {@link DoubleHistogram}.
    *
    * <p>After this method returns the current instance is considered invalid (not being managed by
-   * the instrument).
+   * the instrument). This frees any reserved memory.
    */
   void unbind();
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleUpDownCounter.java

@@ -33,7 +33,7 @@ public interface BoundDoubleUpDownCounter {
    * Unbinds the current bound instance from the {@link DoubleUpDownCounter}.
    *
    * <p>After this method returns the current instance is considered invalid (not being managed by
-   * the instrument).
+   * the instrument). This frees any reserved memory.
    */
   void unbind();
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongCounter.java

@@ -33,7 +33,7 @@ public interface BoundLongCounter {
    * Unbinds the current bound instance from the {@link LongCounter}.
    *
    * <p>After this method returns the current instance is considered invalid (not being managed by
-   * the instrument).
+   * the instrument). This frees any reserved memory.
    */
   void unbind();
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongHistogram.java

@@ -33,7 +33,7 @@ public interface BoundLongHistogram {
    * Unbinds the current bound instance from the {@link LongHistogram}.
    *
    * <p>After this method returns the current instance is considered invalid (not being managed by
-   * the instrument).
+   * the instrument). This frees any reserved memory.
    */
   void unbind();
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongUpDownCounter.java

@@ -33,7 +33,7 @@ public interface BoundLongUpDownCounter {
    * Unbinds the current bound instance from the {@link LongUpDownCounter}.
    *
    * <p>After this method returns the current instance is considered invalid (not being managed by
-   * the instrument).
+   * the instrument). This frees any reserved memory.
    */
   void unbind();
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleCounter.java

@@ -45,6 +45,11 @@ public interface DoubleCounter {
   /**
    * Constructs a bound version of this instrument where all recorded values use the given
    * attributes.
+   *
+   * <p>Bound instruments pre-allocate storage slots for measurements and can help alleviate garbage
+   * collection pressure on high peformance systems. Bound instruments require all attributes to be
+   * known ahead of time, and do not work when configuring metric views which pull attributes from
+   * {@link Context}, e.g. baggage labels.
    */
   BoundDoubleCounter bind(Attributes attributes);
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java

@@ -12,7 +12,7 @@ public interface DoubleCounterBuilder {
   /**
    * Sets the description for this instrument.
    *
-   * <p>Description stirngs should follw the instrument description rules:
+   * <p>Description strings should follow the instrument description rules:
    * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description
    */
   DoubleCounterBuilder setDescription(String description);
@@ -33,10 +33,18 @@ public interface DoubleCounterBuilder {
   DoubleCounter build();
 
   /**
-   * Builds this asynchronous insturment with the given callback.
+   * Builds this asynchronous instrument with the given callback.
    *
    * <p>The callback will only be called when the {@link Meter} is being observed.
    *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   *   <li>Return positive, monotonically increasing values.
+   * </ul>
+   *
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   void buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);

api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java

@@ -33,6 +33,13 @@ public interface DoubleGaugeBuilder {
    *
    * <p>The callback will only be called when the {@link Meter} is being observed.
    *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   void buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);

api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleHistogram.java

@@ -46,6 +46,11 @@ public interface DoubleHistogram {
   /**
    * Constructs a bound version of this instrument where all recorded values use the given
    * attributes.
+   *
+   * <p>Bound instruments pre-allocate storage slots for measurements and can help alleviate garbage
+   * collection pressure on high peformance systems. Bound instruments require all attributes to be
+   * known ahead of time, and do not work when configuring metric views which pull attributes from
+   * {@link Context}, e.g. baggage labels.
    */
   BoundDoubleHistogram bind(Attributes attributes);
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounter.java

@@ -45,6 +45,11 @@ public interface DoubleUpDownCounter {
   /**
    * Constructs a bound version of this instrument where all recorded values use the given
    * attributes.
+   *
+   * <p>Bound instruments pre-allocate storage slots for measurements and can help alleviate garbage
+   * collection pressure on high peformance systems. Bound instruments require all attributes to be
+   * known ahead of time, and do not work when configuring metric views which pull attributes from
+   * {@link Context}, e.g. baggage labels.
    */
   BoundDoubleUpDownCounter bind(Attributes attributes);
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java

@@ -37,6 +37,13 @@ public interface DoubleUpDownCounterBuilder {
    *
    * <p>The callback will only be called when the {@link Meter} is being observed.
    *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   void buildWithCallback(Consumer<ObservableDoubleMeasurement> callback);

api/metrics/src/main/java/io/opentelemetry/api/metrics/LongCounter.java

@@ -9,7 +9,12 @@ import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.context.Context;
 import javax.annotation.concurrent.ThreadSafe;
 
-/** A counter instrument that records {@code long} values. */
+/**
+ * A counter instrument that records {@code long} values.
+ *
+ * <p>Counters only allow adding positive values, and guarantee the resulting metrics will be
+ * always-increasing monotonic sums.
+ */
 @ThreadSafe
 public interface LongCounter {
 
@@ -46,6 +51,11 @@ public interface LongCounter {
   /**
    * Constructs a bound version of this instrument where all recorded values use the given
    * attributes.
+   *
+   * <p>Bound instruments pre-allocate storage slots for measurements and can help alleviate garbage
+   * collection pressure on high peformance systems. Bound instruments require all attributes to be
+   * known ahead of time, and do not work when configuring metric views which pull attributes from
+   * {@link Context}, e.g. baggage labels.
    */
   BoundLongCounter bind(Attributes attributes);
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java

@@ -41,6 +41,14 @@ public interface LongCounterBuilder {
    *
    * <p>The callback will only be called when the {@link Meter} is being observed.
    *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   *   <li>Return positive, monotonically increasing values.
+   * </ul>
+   *
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   void buildWithCallback(Consumer<ObservableLongMeasurement> callback);

api/metrics/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java

@@ -30,6 +30,13 @@ public interface LongGaugeBuilder {
    *
    * <p>The callback will only be called when the {@link Meter} is being observed.
    *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   void buildWithCallback(Consumer<ObservableLongMeasurement> callback);

api/metrics/src/main/java/io/opentelemetry/api/metrics/LongHistogram.java

@@ -46,6 +46,11 @@ public interface LongHistogram {
   /**
    * Construct a bound version of this instrument where all recorded values use the given
    * attributes.
+   *
+   * <p>Bound instruments pre-allocate storage slots for measurements and can help alleviate garbage
+   * collection pressure on high peformance systems. Bound instruments require all attributes to be
+   * known ahead of time, and do not work when configuring metric views which pull attributes from
+   * {@link Context}, e.g. baggage labels.
    */
   BoundLongHistogram bind(Attributes attributes);
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounter.java

@@ -45,6 +45,11 @@ public interface LongUpDownCounter {
   /**
    * Construct a bound version of this instrument where all recorded values use the given
    * attributes.
+   *
+   * <p>Bound instruments pre-allocate storage slots for measurements and can help alleviate garbage
+   * collection pressure on high peformance systems. Bound instruments require all attributes to be
+   * known ahead of time, and do not work when configuring metric views which pull attributes from
+   * {@link Context}, e.g. baggage labels.
    */
   BoundLongUpDownCounter bind(Attributes attributes);
 }

api/metrics/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java

@@ -40,6 +40,13 @@ public interface LongUpDownCounterBuilder {
    *
    * <p>The callback will only be called when the {@link Meter} is being observed.
    *
+   * <p>Callbacks are expected to abide by the following restrictions:
+   *
+   * <ul>
+   *   <li>Run in a finite amount of time.
+   *   <li>Safe to call repeatedly, across multiple threads.
+   * </ul>
+   *
    * @param callback A state-capturing callback used to observe values on-demand.
    */
   void buildWithCallback(Consumer<ObservableLongMeasurement> callback);

api/metrics/src/main/java/io/opentelemetry/api/metrics/Meter.java

@@ -15,6 +15,24 @@ import javax.annotation.concurrent.ThreadSafe;
  *
  * <p>A Meter is generally associated with an instrumentation library, e.g. "I monitor apache
  * httpclient".
+ *
+ * <p>Choosing an instrument can be hard, but here's a rule of thumb for selecting the right
+ * instrument:
+ *
+ * <ul>
+ *   <li>I want to <b>count</b> something.
+ *       <ul>
+ *         <li>The value is always increasing / I want to track its <b>rate</b>.<br>
+ *             Use {@link #counterBuilder(String)}
+ *         <li>The value is not always increasing.<br>
+ *             Use {@link #upDownCounterBuilder(String)}
+ *       </ul>
+ *   <li>I want to <b>time</b> something, or record measurements where the statistics are important
+ *       (e.g. latency).<br>
+ *       <b>Use {@link #histogramBuilder(String)}</b>
+ *   <li>I want to measure something by sampling a value stored elsewhere. <br>
+ *       Use {@link #gaugeBuilder(String)}
+ * </ul>
  */
 @ThreadSafe
 public interface Meter {

api/metrics/src/main/java/io/opentelemetry/api/metrics/MeterBuilder.java

@@ -15,6 +15,9 @@ public interface MeterBuilder {
   /**
    * Assigns an OpenTelemetry schema URL to the resulting Meter.
    *
+   * <p>Schemas are used to identify expected metrics (semantic conventions) and allow backends to
+   * "automatically migrate" to supported versions.
+   *
    * @param schemaUrl The URL of the OpenTelemetry schema being used by this instrumentation
    *     library.
    * @return this

api/metrics/src/main/java/io/opentelemetry/api/metrics/ObservableMeasurement.java

@@ -6,7 +6,7 @@
 package io.opentelemetry.api.metrics;
 
 /**
- * A mechanism for observing measurments.
+ * A mechanism for observing measurements.
  *
  * <p>see {@link ObservableDoubleMeasurement} or {@link ObservableLongMeasurement}.
  */

api/metrics/src/main/java/io/opentelemetry/api/metrics/package-info.java

@@ -3,7 +3,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/** This package describes the Metrics API that can be used to record application Metrics. */
+/**
+ * This package describes the Metrics API that can be used to record application Metrics.
+ *
+ * <p>The primary entry point to Metrics is the {@link io.opentelemetry.api.metrics.MeterProvider},
+ * which allows the construction of a {@link io.opentelemetry.api.metrics.Meter}. Instrumentated
+ * libraries should construct a single {@link io.opentelemetry.api.metrics.Meter} and register
+ * `instruments` via the builders available on {@link io.opentelemetry.api.metrics.Meter}.
+ *
+ * <p>There is a global instance of {@link io.opentelemetry.api.metrics.MeterProvider} available for
+ * scenarios where instrumentation authors are unable to obtain one by other means.
+ */
 @ParametersAreNonnullByDefault
 package io.opentelemetry.api.metrics;