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}. * *
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}. * *
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}. * *
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}. * *
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}. * *
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}. * *
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. + * + *
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. * - *
Description stirngs should follw the instrument description rules: + *
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. * *
The callback will only be called when the {@link Meter} is being observed. * + *
Callbacks are expected to abide by the following restrictions: + * + *
The callback will only be called when the {@link Meter} is being observed. * + *
Callbacks are expected to abide by the following restrictions: + * + *
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. + * + *
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 { * *
The callback will only be called when the {@link Meter} is being observed. * + *
Callbacks are expected to abide by the following restrictions: + * + *
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. + * + *
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 { * *
The callback will only be called when the {@link Meter} is being observed. * + *
Callbacks are expected to abide by the following restrictions: + * + *
The callback will only be called when the {@link Meter} is being observed. * + *
Callbacks are expected to abide by the following restrictions: + * + *
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. + * + *
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 { * *
The callback will only be called when the {@link Meter} is being observed. * + *
Callbacks are expected to abide by the following restrictions: + * + *
A Meter is generally associated with an instrumentation library, e.g. "I monitor apache * httpclient". + * + *
Choosing an instrument can be hard, but here's a rule of thumb for selecting the right + * instrument: + * + *
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. * *
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. + * + *
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}. + * + *
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;