diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramBuckets.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramBuckets.java new file mode 100644 index 00000000000..235823fd4c7 --- /dev/null +++ b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramBuckets.java @@ -0,0 +1,48 @@ +/* + * Copyright The OpenTelemetry Authors + * SPDX-License-Identifier: Apache-2.0 + */ + +package io.opentelemetry.sdk.metrics.data; + +import java.util.List; +import javax.annotation.concurrent.Immutable; + +/** + * ExponentialHistogramBuckets represents either the positive or negative measurements taken for a + * {@link ExponentialHistogramPointData}. + * + *

The bucket boundaries are lower-bound inclusive, and are calculated using the {@link + * ExponentialHistogramPointData#getScale()} and the {@link #getOffset()}. + * + *

For example, assume {@link ExponentialHistogramPointData#getScale()} is 0, the base is 2.0. + * Then, if offset is 0, the bucket lower bounds would be 1.0, 2.0, 4.0, 8.0, etc. If + * offset is -3, the bucket lower bounds would be 0.125, 0.25, 0.5, 1.0, 2,0, etc. If + * offset is +3, the bucket lower bounds would be 8.0, 16.0, 32.0, etc. + */ +@Immutable +public interface ExponentialHistogramBuckets { + + /** + * The offset shifts the bucket boundaries according to lower_bound = base^(offset+i). + * . + * + * @return the offset. + */ + int getOffset(); + + /** + * The bucket counts is a of counts representing number of measurements that fall into each + * bucket. + * + * @return the bucket counts. + */ + List getBucketCounts(); + + /** + * The total count is the sum of all the values in the buckets. + * + * @return the total count. + */ + long getTotalCount(); +} diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramData.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramData.java new file mode 100644 index 00000000000..9a2910a2739 --- /dev/null +++ b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramData.java @@ -0,0 +1,43 @@ +/* + * Copyright The OpenTelemetry Authors + * SPDX-License-Identifier: Apache-2.0 + */ + +package io.opentelemetry.sdk.metrics.data; + +import java.util.Collection; +import javax.annotation.concurrent.Immutable; + +/** + * A base-2 exponential histogram metric point, as defined by the OpenTelemetry Exponential + * Histogram specification. + * + *

See {@link ExponentialHistogramPointData} for more information. + * + *

See: + * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/datamodel.md#exponentialhistogram + * + *

Note: This is called "ExponentialHistogramData" to reflect which primitives are used to + * record it, however "ExponentialHistogram" is the equivalent OTLP type. + */ +@Immutable +public interface ExponentialHistogramData extends Data { + + /** + * Returns the {@code AggregationTemporality} of this metric. + * + *

AggregationTemporality describes if the aggregator reports delta changes since last report + * time, or cumulative changes since a fixed start time. + * + * @return the {@code AggregationTemporality} of this metric + */ + AggregationTemporality getAggregationTemporality(); + + /** + * Returns the collection of {@link ExponentialHistogramPointData} for this histogram. + * + * @return the collection of data points for this histogram. + */ + @Override + Collection getPoints(); +} diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramPointData.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramPointData.java new file mode 100644 index 00000000000..31da82b50a0 --- /dev/null +++ b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramPointData.java @@ -0,0 +1,71 @@ +/* + * Copyright The OpenTelemetry Authors + * SPDX-License-Identifier: Apache-2.0 + */ + +package io.opentelemetry.sdk.metrics.data; + +import javax.annotation.concurrent.Immutable; + +/** + * ExponentialHistogramPointData represents an approximate distribution of measurements across + * exponentially increasing bucket boundaries, taken for a {@link ExponentialHistogramData}. It + * contains the necessary information to calculate bucket boundaries and perform aggregation. + * + *

The bucket boundaries are calculated using both the scale {@link #getScale()}, and the offset + * {@link ExponentialHistogramBuckets#getOffset()}. + * + *

See: + * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/datamodel.md#exponentialhistogram + */ +@Immutable +public interface ExponentialHistogramPointData extends PointData { + + /** + * Scale characterises the resolution of the histogram, with larger values of scale offering + * greater precision. Bucket boundaries of the histogram are located at integer powers of the + * base, where base = Math.pow(2, Math.pow(2, -scale)). + * + * @return the scale. + */ + int getScale(); + + /** + * Returns the sum of all measurements in the data point. The sum should be disregarded if there + * are both positive and negative measurements. + * + * @return the sum of all measurements in this data point. + */ + double getSum(); + + /** + * Returns the number of measurements taken for this data point, including the positive bucket + * counts, negative bucket counts, and the zero count. + * + * @return the number of measurements in this data point. + */ + long getCount(); + + /** + * Returns the number of measurements equal to zero in this data point. + * + * @return the number of values equal to zero. + */ + long getZeroCount(); + + /** + * Return the {@link ExponentialHistogramBuckets} representing the positive measurements taken for + * this histogram. + * + * @return the positive buckets. + */ + ExponentialHistogramBuckets getPositiveBuckets(); + + /** + * Return the {@link ExponentialHistogramBuckets} representing the negative measurements taken for + * this histogram. + * + * @return the negative buckets. + */ + ExponentialHistogramBuckets getNegativeBuckets(); +}