From 19f6fa79f0c3bcba10367b78e6454356c0372903 Mon Sep 17 00:00:00 2001
From: Josh Suereth <joshuasuereth@google.com>
Date: Wed, 17 Nov 2021 15:53:46 -0500
Subject: [PATCH] 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/BoundDoubleCounter.java        |  2 +-
 .../api/metrics/BoundDoubleHistogram.java      |  2 +-
 .../api/metrics/BoundDoubleUpDownCounter.java  |  2 +-
 .../api/metrics/BoundLongCounter.java          |  2 +-
 .../api/metrics/BoundLongHistogram.java        |  2 +-
 .../api/metrics/BoundLongUpDownCounter.java    |  2 +-
 .../api/metrics/DoubleCounter.java             |  5 +++++
 .../api/metrics/DoubleCounterBuilder.java      | 12 ++++++++++--
 .../api/metrics/DoubleGaugeBuilder.java        |  7 +++++++
 .../api/metrics/DoubleHistogram.java           |  5 +++++
 .../api/metrics/DoubleUpDownCounter.java       |  5 +++++
 .../metrics/DoubleUpDownCounterBuilder.java    |  7 +++++++
 .../opentelemetry/api/metrics/LongCounter.java | 12 +++++++++++-
 .../api/metrics/LongCounterBuilder.java        |  8 ++++++++
 .../api/metrics/LongGaugeBuilder.java          |  7 +++++++
 .../api/metrics/LongHistogram.java             |  5 +++++
 .../api/metrics/LongUpDownCounter.java         |  5 +++++
 .../api/metrics/LongUpDownCounterBuilder.java  |  7 +++++++
 .../io/opentelemetry/api/metrics/Meter.java    | 18 ++++++++++++++++++
 .../api/metrics/MeterBuilder.java              |  3 +++
 .../api/metrics/ObservableMeasurement.java     |  2 +-
 .../api/metrics/package-info.java              | 12 +++++++++++-
 22 files changed, 121 insertions(+), 11 deletions(-)

diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleCounter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleCounter.java
index d6233d317d..3a0811a4f8 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleCounter.java
+++ b/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();
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleHistogram.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleHistogram.java
index 45e2527e46..c5dd52f8c4 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleHistogram.java
+++ b/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();
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleUpDownCounter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleUpDownCounter.java
index 6393b9a018..e414bc6849 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundDoubleUpDownCounter.java
+++ b/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();
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongCounter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongCounter.java
index 81fb520af1..4c9f818b81 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongCounter.java
+++ b/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();
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongHistogram.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongHistogram.java
index 24997f6e04..04a69f301f 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongHistogram.java
+++ b/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();
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongUpDownCounter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongUpDownCounter.java
index 7ca78a37b8..4ba4af53fc 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/BoundLongUpDownCounter.java
+++ b/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();
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleCounter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleCounter.java
index 33d11e25ca..295c4175a3 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleCounter.java
+++ b/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);
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java
index 9f9a757da6..24790900cb 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleCounterBuilder.java
+++ b/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);
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java
index a1a5d4c7ef..8440a5a169 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleGaugeBuilder.java
+++ b/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);
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleHistogram.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleHistogram.java
index 1205acf9aa..41b44c1f0e 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleHistogram.java
+++ b/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);
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounter.java
index d8af95372e..a8b7fa844a 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounter.java
+++ b/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);
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java
index 8dc7db855f..7d26db9d32 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounterBuilder.java
+++ b/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);
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongCounter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongCounter.java
index 6fdbd2c479..4ad44646ea 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongCounter.java
+++ b/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);
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java
index 0361517dbf..ece92bc73a 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongCounterBuilder.java
+++ b/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);
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java
index ae959f62df..5f7bdca76d 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongGaugeBuilder.java
+++ b/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);
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongHistogram.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongHistogram.java
index f074b1bf7b..12f1329f5e 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongHistogram.java
+++ b/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);
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounter.java
index 2867963598..669cd3509f 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounter.java
+++ b/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);
 }
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java
index ba17ea2686..15bb80393e 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounterBuilder.java
+++ b/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);
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/Meter.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/Meter.java
index 681a82ed76..b3a480ae32 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/Meter.java
+++ b/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 {
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/MeterBuilder.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/MeterBuilder.java
index 680ddf2fc9..cc445ba1e3 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/MeterBuilder.java
+++ b/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
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/ObservableMeasurement.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/ObservableMeasurement.java
index 1a20132362..6817ba5a3a 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/ObservableMeasurement.java
+++ b/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}.
  */
diff --git a/api/metrics/src/main/java/io/opentelemetry/api/metrics/package-info.java b/api/metrics/src/main/java/io/opentelemetry/api/metrics/package-info.java
index 5d27ed340d..5df45ba379 100644
--- a/api/metrics/src/main/java/io/opentelemetry/api/metrics/package-info.java
+++ b/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;