Tighten up metrics sdk javadoc (#4508)

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/Aggregation.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.sdk.metrics;
 
+import io.opentelemetry.sdk.metrics.data.MetricDataType;
 import io.opentelemetry.sdk.metrics.internal.view.DefaultAggregation;
 import io.opentelemetry.sdk.metrics.internal.view.DropAggregation;
 import io.opentelemetry.sdk.metrics.internal.view.ExplicitBucketHistogramAggregation;
@@ -13,43 +14,52 @@
 import java.util.List;
 
 /**
- * Configures how measurements are combined into metrics.
+ * Configures how instrument measurements are combined into metrics.
  *
  * <p>Aggregation provides a set of built-in aggregations via static methods.
+ *
+ * @since 1.14.0
  */
 // TODO(anuraaga): Have methods when custom aggregations are supported.
 @SuppressWarnings("InterfaceWithOnlyStatics")
 public interface Aggregation {
 
-  /** The drop Aggregation will ignore/drop all Instrument Measurements. */
+  /** Drops all measurements and don't export any metric. */
   static Aggregation drop() {
     return DropAggregation.getInstance();
   }
 
-  /** The default aggregation for an instrument will be chosen. */
+  /** Choose the default aggregation for the {@link InstrumentType}. */
   static Aggregation defaultAggregation() {
     return DefaultAggregation.getInstance();
   }
 
-  /** Instrument measurements will be combined into a metric Sum. */
+  /**
+   * Aggregates measurements into a {@link MetricDataType#DOUBLE_SUM} or {@link
+   * MetricDataType#LONG_SUM}.
+   */
   static Aggregation sum() {
     return SumAggregation.getInstance();
   }
 
-  /** Remembers the last seen measurement and reports as a Gauge. */
+  /**
+   * Records the last seen measurement as a {@link MetricDataType#DOUBLE_GAUGE} or {@link
+   * MetricDataType#LONG_GAUGE}.
+   */
   static Aggregation lastValue() {
     return LastValueAggregation.getInstance();
   }
 
   /**
-   * Aggregates measurements into an explicit bucket histogram using the default bucket boundaries.
+   * Aggregates measurements into an explicit bucket {@link MetricDataType#HISTOGRAM} using the
+   * default bucket boundaries.
    */
   static Aggregation explicitBucketHistogram() {
     return ExplicitBucketHistogramAggregation.getDefault();
   }
 
   /**
-   * Aggregates measurements into an explicit bucket histogram.
+   * Aggregates measurements into an explicit bucket {@link MetricDataType#HISTOGRAM}.
    *
    * @param bucketBoundaries A list of (inclusive) upper bounds for the histogram. Should be in
    *     order from lowest to highest.

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/InstrumentSelector.java

@@ -11,8 +11,14 @@
 import javax.annotation.concurrent.Immutable;
 
 /**
- * Provides means for selecting one or more instruments. Used for configuring aggregations for the
- * specified instruments.
+ * Instrument selection criteria for applying {@link View}s registered via {@link
+ * SdkMeterProviderBuilder#registerView(InstrumentSelector, View)}.
+ *
+ * <p>Properties are ANDed together. For example, if {@link #getInstrumentName()} is
+ * "http.server.duration" and {@link #getMeterName()} is "my.http.meter", then instruments are
+ * selected where name is "http.server.duration" AND meter name is "my.http.meter".
+ *
+ * @since 1.14.0
  */
 @AutoValue
 @Immutable
@@ -35,15 +41,12 @@ static InstrumentSelector create(
 
   InstrumentSelector() {}
 
-  /**
-   * Returns selection criteria for {@link InstrumentType}. If null, select instruments with any
-   * type.
-   */
+  /** Returns the selected {@link InstrumentType}, or null if this selects all instrument types. */
   @Nullable
   public abstract InstrumentType getInstrumentType();
 
   /**
-   * Returns the selection criteria for instrument name. If null, select instruments with any name.
+   * Returns the selected instrument name, or null if this selects all instrument names.
    *
    * <p>Instrument name may contain the wildcard characters {@code *} and {@code ?} with the
    * following matching criteria:
@@ -56,23 +59,20 @@ static InstrumentSelector create(
   @Nullable
   public abstract String getInstrumentName();
 
-  /**
-   * Returns the selection criteria for meter name. If null, select instruments from meters with any
-   * name.
-   */
+  /** Returns the selected meter name, or null if this selects instruments from all meter names. */
   @Nullable
   public abstract String getMeterName();
 
   /**
-   * Returns the selection criteria for meter version. If null, select instruments from meters with
-   * any version.
+   * Returns the selected meter version, or null if this selects instruments from all meter
+   * versions.
    */
   @Nullable
   public abstract String getMeterVersion();
 
   /**
-   * Returns the selection criteria for meter schema url. If null, select instruments from meters
-   * with any schema url.
+   * Returns the selected meter schema url, or null if this selects instruments from all meter
+   * schema urls.
    */
   @Nullable
   public abstract String getMeterSchemaUrl();

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/InstrumentSelectorBuilder.java

@@ -10,7 +10,11 @@
 
 import javax.annotation.Nullable;
 
-/** Builder for {@link InstrumentSelector}. */
+/**
+ * Builder for {@link InstrumentSelector}.
+ *
+ * @since 1.14.0
+ */
 public final class InstrumentSelectorBuilder {
 
   @Nullable private InstrumentType instrumentType;
@@ -21,15 +25,15 @@ public final class InstrumentSelectorBuilder {
 
   InstrumentSelectorBuilder() {}
 
-  /** Sets a specifier for {@link InstrumentType}. */
+  /** Select instruments with the given {@code instrumentType}. */
   public InstrumentSelectorBuilder setType(InstrumentType instrumentType) {
     requireNonNull(instrumentType, "instrumentType");
     this.instrumentType = instrumentType;
     return this;
   }
 
   /**
-   * Sets the exact instrument name that will be selected.
+   * Select instruments with the given {@code name}.
    *
    * <p>Instrument name may contain the wildcard characters {@code *} and {@code ?} with the
    * following matching criteria:
@@ -45,37 +49,28 @@ public InstrumentSelectorBuilder setName(String name) {
     return this;
   }
 
-  /**
-   * Sets a specifier for selecting instruments by the name of their associated {@link
-   * io.opentelemetry.api.metrics.Meter}.
-   */
+  /** Select instruments associated with the given {@code meterName}. */
   public InstrumentSelectorBuilder setMeterName(String meterName) {
     requireNonNull(meterName, "meterName");
     this.meterName = meterName;
     return this;
   }
 
-  /**
-   * Sets a specifier for selecting instruments by the version of their associated {@link
-   * io.opentelemetry.api.metrics.Meter}.
-   */
+  /** Select instruments associated with the given {@code meterVersion}. */
   public InstrumentSelectorBuilder setMeterVersion(String meterVersion) {
     requireNonNull(meterVersion, "meterVersion");
     this.meterVersion = meterVersion;
     return this;
   }
 
-  /**
-   * Sets a specifier for selecting instruments by the schema URL of their associated {@link
-   * io.opentelemetry.api.metrics.Meter}.
-   */
+  /** Select instruments associated with the given {@code meterSchemaUrl}. */
   public InstrumentSelectorBuilder setMeterSchemaUrl(String meterSchemaUrl) {
     requireNonNull(meterSchemaUrl, "meterSchemaUrl");
     this.meterSchemaUrl = meterSchemaUrl;
     return this;
   }
 
-  /** Returns an InstrumentSelector instance with the content of this builder. */
+  /** Returns an {@link InstrumentSelector} with the configuration of this builder. */
   public InstrumentSelector build() {
     checkArgument(
         instrumentType != null

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/InstrumentType.java

@@ -5,7 +5,11 @@
 
 package io.opentelemetry.sdk.metrics;
 
-/** All instrument types available in the metric package. */
+/**
+ * All possible instrument types.
+ *
+ * @since 1.14.0
+ */
 public enum InstrumentType {
   COUNTER,
   UP_DOWN_COUNTER,

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/InstrumentValueType.java

@@ -5,7 +5,11 @@
 
 package io.opentelemetry.sdk.metrics;
 
-/** All possible types for the values recorded via the instruments. */
+/**
+ * All possible measurement value types.
+ *
+ * @since 1.14.0
+ */
 public enum InstrumentValueType {
   LONG,
   DOUBLE,

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkMeter.java

@@ -62,7 +62,7 @@ InstrumentationScopeInfo getInstrumentationScopeInfo() {
     return instrumentationScopeInfo;
   }
 
-  /** Collects all the metric recordings that changed since the previous call. */
+  /** Collect all metrics for the meter. */
   Collection<MetricData> collectAll(RegisteredReader registeredReader, long epochNanos) {
     return meterSharedState.collectAll(registeredReader, meterProviderSharedState, epochNanos);
   }

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkMeterProvider.java

@@ -14,6 +14,7 @@
 import io.opentelemetry.sdk.internal.ComponentRegistry;
 import io.opentelemetry.sdk.metrics.data.MetricData;
 import io.opentelemetry.sdk.metrics.export.MetricReader;
+import io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil;
 import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.internal.export.MetricProducer;
 import io.opentelemetry.sdk.metrics.internal.export.RegisteredReader;
@@ -29,7 +30,11 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.logging.Logger;
 
-/** SDK implementation for {@link MeterProvider}. */
+/**
+ * SDK implementation for {@link MeterProvider}.
+ *
+ * @since 1.14.0
+ */
 public final class SdkMeterProvider implements MeterProvider, Closeable {
 
   private static final Logger LOGGER = Logger.getLogger(SdkMeterProvider.class.getName());
@@ -40,11 +45,7 @@ public final class SdkMeterProvider implements MeterProvider, Closeable {
   private final ComponentRegistry<SdkMeter> registry;
   private final AtomicBoolean isClosed = new AtomicBoolean(false);
 
-  /**
-   * Returns a new {@link SdkMeterProviderBuilder} for {@link SdkMeterProvider}.
-   *
-   * @return a new {@link SdkMeterProviderBuilder} for {@link SdkMeterProvider}.
-   */
+  /** Returns a new {@link SdkMeterProviderBuilder} for {@link SdkMeterProvider}. */
   public static SdkMeterProviderBuilder builder() {
     return new SdkMeterProviderBuilder();
   }
@@ -83,7 +84,12 @@ public MeterBuilder meterBuilder(String instrumentationScopeName) {
     return new SdkMeterBuilder(registry, instrumentationScopeName);
   }
 
-  /** Reset the provider, clearing all registered instruments. */
+  /**
+   * Reset the provider, clearing all registered instruments.
+   *
+   * <p>Note: not currently stable but available for experimental use via {@link
+   * SdkMeterProviderUtil#resetForTest(SdkMeterProvider)}.
+   */
   void resetForTest() {
     registry.getComponents().forEach(SdkMeter::resetForTest);
   }