Data classes for exponential histogram prototype (#3550) (#3637)

* Data classes for exponential histogram prototype (#3550)

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}.
+ *
+ * <p>The bucket boundaries are lower-bound inclusive, and are calculated using the {@link
+ * ExponentialHistogramPointData#getScale()} and the {@link #getOffset()}.
+ *
+ * <p>For example, assume {@link ExponentialHistogramPointData#getScale()} is 0, the base is 2.0.
+ * Then, if <code>offset</code> is 0, the bucket lower bounds would be 1.0, 2.0, 4.0, 8.0, etc. If
+ * <code>offset</code> is -3, the bucket lower bounds would be 0.125, 0.25, 0.5, 1.0, 2,0, etc. If
+ * <code>offset</code> 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 <code>lower_bound = base^(offset+i).
+   * </code>.
+   *
+   * @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<Long> getBucketCounts();
+
+  /**
+   * The total count is the sum of all the values in the buckets.
+   *
+   * @return the total count.
+   */
+  long getTotalCount();
+}

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.
+ *
+ * <p>See {@link ExponentialHistogramPointData} for more information.
+ *
+ * <p>See:
+ * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/datamodel.md#exponentialhistogram
+ *
+ * <p><i>Note: This is called "ExponentialHistogramData" to reflect which primitives are used to
+ * record it, however "ExponentialHistogram" is the equivalent OTLP type.</i>
+ */
+@Immutable
+public interface ExponentialHistogramData extends Data<ExponentialHistogramPointData> {
+
+  /**
+   * Returns the {@code AggregationTemporality} of this metric.
+   *
+   * <p>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<ExponentialHistogramPointData> getPoints();
+}

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.
+ *
+ * <p>The bucket boundaries are calculated using both the scale {@link #getScale()}, and the offset
+ * {@link ExponentialHistogramBuckets#getOffset()}.
+ *
+ * <p>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 <code>base = Math.pow(2, Math.pow(2, -scale))</code>.
+   *
+   * @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();
+}