feat: Allow configuring of min/max in histograms

docs/apidiffs/current_vs_latest/opentelemetry-sdk-metrics.txt

@@ -1,2 +1,5 @@
 Comparing source compatibility of opentelemetry-sdk-metrics-1.60.0-SNAPSHOT.jar against opentelemetry-sdk-metrics-1.59.0.jar
-No changes.
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.Aggregation  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.Aggregation base2ExponentialBucketHistogram(int, int, boolean)
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.Aggregation explicitBucketHistogram(java.util.List<java.lang.Double>, boolean)

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/AggregationFactory.java

@@ -10,6 +10,7 @@
 import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.Base2ExponentialBucketHistogramAggregationModel;
 import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.ExplicitBucketHistogramAggregationModel;
 import io.opentelemetry.sdk.metrics.Aggregation;
+import io.opentelemetry.sdk.metrics.internal.aggregator.ExplicitBucketHistogramUtils;
 import java.util.List;
 
 final class AggregationFactory implements Factory<AggregationModel, Aggregation> {
@@ -44,8 +45,10 @@ public Aggregation create(AggregationModel model, DeclarativeConfigContext conte
       if (maxSize == null) {
         maxSize = 160;
       }
+      Boolean recordMinMax = exponentialBucketHistogram.getRecordMinMax();
+      boolean shouldRecordMinMax = recordMinMax != null ? recordMinMax : true;
       try {
-        return Aggregation.base2ExponentialBucketHistogram(maxSize, maxScale);
+        return Aggregation.base2ExponentialBucketHistogram(maxSize, maxScale, shouldRecordMinMax);
       } catch (IllegalArgumentException e) {
         throw new DeclarativeConfigException("Invalid exponential bucket histogram", e);
       }
@@ -54,11 +57,15 @@ public Aggregation create(AggregationModel model, DeclarativeConfigContext conte
         model.getExplicitBucketHistogram();
     if (explicitBucketHistogram != null) {
       List<Double> boundaries = explicitBucketHistogram.getBoundaries();
+      Boolean recordMinMax = explicitBucketHistogram.getRecordMinMax();
+      boolean shouldRecordMinMax = recordMinMax != null ? recordMinMax : true;
       if (boundaries == null) {
-        return Aggregation.explicitBucketHistogram();
+        // Use default boundaries with recordMinMax parameter
+        return Aggregation.explicitBucketHistogram(
+            ExplicitBucketHistogramUtils.DEFAULT_HISTOGRAM_BUCKET_BOUNDARIES, shouldRecordMinMax);
       }
       try {
-        return Aggregation.explicitBucketHistogram(boundaries);
+        return Aggregation.explicitBucketHistogram(boundaries, shouldRecordMinMax);
       } catch (IllegalArgumentException e) {
         throw new DeclarativeConfigException("Invalid explicit bucket histogram", e);
       }

sdk-extensions/incubator/src/test/java/io/opentelemetry/sdk/extension/incubator/fileconfig/AggregationFactoryTest.java

@@ -62,6 +62,49 @@ private static Stream<Arguments> createTestCases() {
                 .withExplicitBucketHistogram(
                     new ExplicitBucketHistogramAggregationModel()
                         .withBoundaries(Arrays.asList(1.0, 2.0))),
-            Aggregation.explicitBucketHistogram(Arrays.asList(1.0, 2.0))));
+            Aggregation.explicitBucketHistogram(Arrays.asList(1.0, 2.0))),
+        // Test recordMinMax parameter for explicit bucket histogram
+        Arguments.of(
+            new AggregationModel()
+                .withExplicitBucketHistogram(
+                    new ExplicitBucketHistogramAggregationModel()
+                        .withBoundaries(Arrays.asList(1.0, 2.0))
+                        .withRecordMinMax(true)),
+            Aggregation.explicitBucketHistogram(Arrays.asList(1.0, 2.0), true)),
+        Arguments.of(
+            new AggregationModel()
+                .withExplicitBucketHistogram(
+                    new ExplicitBucketHistogramAggregationModel()
+                        .withBoundaries(Arrays.asList(1.0, 2.0))
+                        .withRecordMinMax(false)),
+            Aggregation.explicitBucketHistogram(Arrays.asList(1.0, 2.0), false)),
+        Arguments.of(
+            new AggregationModel()
+                .withExplicitBucketHistogram(
+                    new ExplicitBucketHistogramAggregationModel()
+                        .withBoundaries(null)
+                        .withRecordMinMax(false)),
+            Aggregation.explicitBucketHistogram(
+                Arrays.asList(
+                    0.0, 5.0, 10.0, 25.0, 50.0, 75.0, 100.0, 250.0, 500.0, 750.0, 1000.0, 2500.0,
+                    5000.0, 7500.0, 10000.0),
+                false)),
+        // Test recordMinMax parameter for exponential bucket histogram
+        Arguments.of(
+            new AggregationModel()
+                .withBase2ExponentialBucketHistogram(
+                    new Base2ExponentialBucketHistogramAggregationModel()
+                        .withMaxSize(2)
+                        .withMaxScale(2)
+                        .withRecordMinMax(true)),
+            Aggregation.base2ExponentialBucketHistogram(2, 2, true)),
+        Arguments.of(
+            new AggregationModel()
+                .withBase2ExponentialBucketHistogram(
+                    new Base2ExponentialBucketHistogramAggregationModel()
+                        .withMaxSize(2)
+                        .withMaxScale(2)
+                        .withRecordMinMax(false)),
+            Aggregation.base2ExponentialBucketHistogram(2, 2, false)));
   }
 }

sdk/metrics/src/jmh/java/io/opentelemetry/sdk/metrics/internal/aggregator/HistogramAggregationParam.java

@@ -17,19 +17,21 @@ public enum HistogramAggregationParam {
       new DoubleExplicitBucketHistogramAggregator(
           ExplicitBucketHistogramUtils.createBoundaryArray(
               ExplicitBucketHistogramUtils.DEFAULT_HISTOGRAM_BUCKET_BOUNDARIES),
+          /* recordMinMax= */ true,
           ExemplarReservoirFactory.noSamples(),
           IMMUTABLE_DATA)),
   EXPLICIT_SINGLE_BUCKET(
       new DoubleExplicitBucketHistogramAggregator(
           ExplicitBucketHistogramUtils.createBoundaryArray(Collections.emptyList()),
+          /* recordMinMax= */ true,
           ExemplarReservoirFactory.noSamples(),
           IMMUTABLE_DATA)),
   EXPONENTIAL_SMALL_CIRCULAR_BUFFER(
       new DoubleBase2ExponentialHistogramAggregator(
-          ExemplarReservoirFactory.noSamples(), 20, 0, IMMUTABLE_DATA)),
+          ExemplarReservoirFactory.noSamples(), 20, 0, /* recordMinMax= */ true, IMMUTABLE_DATA)),
   EXPONENTIAL_CIRCULAR_BUFFER(
       new DoubleBase2ExponentialHistogramAggregator(
-          ExemplarReservoirFactory.noSamples(), 160, 0, IMMUTABLE_DATA));
+          ExemplarReservoirFactory.noSamples(), 160, 0, /* recordMinMax= */ true, IMMUTABLE_DATA));
 
   private final Aggregator<?> aggregator;
 

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

@@ -69,6 +69,18 @@ static Aggregation explicitBucketHistogram(List<Double> bucketBoundaries) {
     return ExplicitBucketHistogramAggregation.create(bucketBoundaries);
   }
 
+  /**
+   * 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.
+   * @param recordMinMax whether to record min and max values
+   * @since 1.45.0
+   */
+  static Aggregation explicitBucketHistogram(List<Double> bucketBoundaries, boolean recordMinMax) {
+    return ExplicitBucketHistogramAggregation.create(bucketBoundaries, recordMinMax);
+  }
+
   /**
    * Aggregates measurements into a base-2 {@link MetricDataType#EXPONENTIAL_HISTOGRAM} using the
    * default {@code maxBuckets} and {@code maxScale}.
@@ -93,4 +105,21 @@ static Aggregation base2ExponentialBucketHistogram() {
   static Aggregation base2ExponentialBucketHistogram(int maxBuckets, int maxScale) {
     return Base2ExponentialHistogramAggregation.create(maxBuckets, maxScale);
   }
+
+  /**
+   * Aggregates measurements into a base-2 {@link MetricDataType#EXPONENTIAL_HISTOGRAM}.
+   *
+   * @param maxBuckets the max number of positive buckets and negative buckets (max total buckets is
+   *     2 * {@code maxBuckets} + 1 zero bucket).
+   * @param maxScale the maximum and initial scale. If measurements can't fit in a particular scale
+   *     given the {@code maxBuckets}, the scale is reduced until the measurements can be
+   *     accommodated. Setting maxScale may reduce the number of downscales. Additionally, the
+   *     performance of computing bucket index is improved when scale is {@code <= 0}.
+   * @param recordMinMax whether to record min and max values
+   * @since 1.45.0
+   */
+  static Aggregation base2ExponentialBucketHistogram(
+      int maxBuckets, int maxScale, boolean recordMinMax) {
+    return Base2ExponentialHistogramAggregation.create(maxBuckets, maxScale, recordMinMax);
+  }
 }

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/aggregator/DoubleBase2ExponentialHistogramAggregator.java

@@ -40,27 +40,34 @@ public final class DoubleBase2ExponentialHistogramAggregator
   private final ExemplarReservoirFactory reservoirFactory;
   private final int maxBuckets;
   private final int maxScale;
+  private final boolean recordMinMax;
   private final MemoryMode memoryMode;
 
   /**
    * Constructs an exponential histogram aggregator.
    *
    * @param reservoirFactory Supplier of exemplar reservoirs per-stream.
+   * @param maxBuckets maximum number of buckets in each of the positive and negative ranges
+   * @param maxScale maximum scale factor
+   * @param recordMinMax whether to record min and max values
+   * @param memoryMode The {@link MemoryMode} to use in this aggregator.
    */
   public DoubleBase2ExponentialHistogramAggregator(
       ExemplarReservoirFactory reservoirFactory,
       int maxBuckets,
       int maxScale,
+      boolean recordMinMax,
       MemoryMode memoryMode) {
     this.reservoirFactory = reservoirFactory;
     this.maxBuckets = maxBuckets;
     this.maxScale = maxScale;
+    this.recordMinMax = recordMinMax;
     this.memoryMode = memoryMode;
   }
 
   @Override
   public AggregatorHandle<ExponentialHistogramPointData> createHandle() {
-    return new Handle(reservoirFactory, maxBuckets, maxScale, memoryMode);
+    return new Handle(reservoirFactory, maxBuckets, maxScale, recordMinMax, memoryMode);
   }
 
   @Override
@@ -82,6 +89,7 @@ public MetricData toMetricData(
   static final class Handle extends AggregatorHandle<ExponentialHistogramPointData> {
     private final int maxBuckets;
     private final int maxScale;
+    private final boolean recordMinMax;
     @Nullable private DoubleBase2ExponentialHistogramBuckets positiveBuckets;
     @Nullable private DoubleBase2ExponentialHistogramBuckets negativeBuckets;
     private long zeroCount;
@@ -99,10 +107,12 @@ static final class Handle extends AggregatorHandle<ExponentialHistogramPointData
         ExemplarReservoirFactory reservoirFactory,
         int maxBuckets,
         int maxScale,
+        boolean recordMinMax,
         MemoryMode memoryMode) {
       super(reservoirFactory, /* isDoubleType= */ true);
       this.maxBuckets = maxBuckets;
       this.maxScale = maxScale;
+      this.recordMinMax = recordMinMax;
       this.sum = 0;
       this.zeroCount = 0;
       this.min = Double.MAX_VALUE;
@@ -131,10 +141,10 @@ protected synchronized ExponentialHistogramPointData doAggregateThenMaybeResetDo
                 currentScale,
                 sum,
                 zeroCount,
-                this.count > 0,
-                this.min,
-                this.count > 0,
-                this.max,
+                recordMinMax && this.count > 0,
+                recordMinMax ? this.min : 0,
+                recordMinMax && this.count > 0,
+                recordMinMax ? this.max : 0,
                 resolveBuckets(
                     this.positiveBuckets, currentScale, reset, /* reusableBuckets= */ null),
                 resolveBuckets(
@@ -149,10 +159,10 @@ protected synchronized ExponentialHistogramPointData doAggregateThenMaybeResetDo
                 currentScale,
                 sum,
                 zeroCount,
-                this.count > 0,
-                this.min,
-                this.count > 0,
-                this.max,
+                recordMinMax && this.count > 0,
+                recordMinMax ? this.min : 0,
+                recordMinMax && this.count > 0,
+                recordMinMax ? this.max : 0,
                 resolveBuckets(
                     this.positiveBuckets, currentScale, reset, reusablePoint.getPositiveBuckets()),
                 resolveBuckets(
@@ -222,8 +232,10 @@ protected synchronized void doRecordDouble(double value) {
 
       sum += value;
 
-      this.min = Math.min(this.min, value);
-      this.max = Math.max(this.max, value);
+      if (recordMinMax) {
+        this.min = Math.min(this.min, value);
+        this.max = Math.max(this.max, value);
+      }
       count++;
 
       int c = Double.compare(value, 0);

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/aggregator/DoubleExplicitBucketHistogramAggregator.java

@@ -38,6 +38,7 @@
 public final class DoubleExplicitBucketHistogramAggregator
     implements Aggregator<HistogramPointData> {
   private final double[] boundaries;
+  private final boolean recordMinMax;
   private final MemoryMode memoryMode;
 
   // a cache for converting to MetricData
@@ -49,12 +50,17 @@ public final class DoubleExplicitBucketHistogramAggregator
    * Constructs an explicit bucket histogram aggregator.
    *
    * @param boundaries Bucket boundaries, in-order.
+   * @param recordMinMax whether to record min and max values
    * @param reservoirFactory Supplier of exemplar reservoirs per-stream.
    * @param memoryMode The {@link MemoryMode} to use in this aggregator.
    */
   public DoubleExplicitBucketHistogramAggregator(
-      double[] boundaries, ExemplarReservoirFactory reservoirFactory, MemoryMode memoryMode) {
+      double[] boundaries,
+      boolean recordMinMax,
+      ExemplarReservoirFactory reservoirFactory,
+      MemoryMode memoryMode) {
     this.boundaries = boundaries;
+    this.recordMinMax = recordMinMax;
     this.memoryMode = memoryMode;
 
     List<Double> boundaryList = new ArrayList<>(this.boundaries.length);
@@ -67,7 +73,7 @@ public DoubleExplicitBucketHistogramAggregator(
 
   @Override
   public AggregatorHandle<HistogramPointData> createHandle() {
-    return new Handle(boundaryList, boundaries, reservoirFactory, memoryMode);
+    return new Handle(boundaryList, boundaries, recordMinMax, reservoirFactory, memoryMode);
   }
 
   @Override
@@ -91,6 +97,8 @@ static final class Handle extends AggregatorHandle<HistogramPointData> {
     private final List<Double> boundaryList;
     // read-only
     private final double[] boundaries;
+    // read-only
+    private final boolean recordMinMax;
 
     private final Object lock = new Object();
 
@@ -115,11 +123,13 @@ static final class Handle extends AggregatorHandle<HistogramPointData> {
     Handle(
         List<Double> boundaryList,
         double[] boundaries,
+        boolean recordMinMax,
         ExemplarReservoirFactory reservoirFactory,
         MemoryMode memoryMode) {
       super(reservoirFactory, /* isDoubleType= */ true);
       this.boundaryList = boundaryList;
       this.boundaries = boundaries;
+      this.recordMinMax = recordMinMax;
       this.counts = new long[this.boundaries.length + 1];
       this.sum = 0;
       this.min = Double.MAX_VALUE;
@@ -156,10 +166,10 @@ protected HistogramPointData doAggregateThenMaybeResetDoubles(
                   epochNanos,
                   attributes,
                   sum,
-                  this.count > 0,
-                  this.min,
-                  this.count > 0,
-                  this.max,
+                  recordMinMax && this.count > 0,
+                  recordMinMax ? this.min : 0,
+                  recordMinMax && this.count > 0,
+                  recordMinMax ? this.max : 0,
                   boundaryList,
                   PrimitiveLongList.wrap(Arrays.copyOf(counts, counts.length)),
                   exemplars);
@@ -170,10 +180,10 @@ protected HistogramPointData doAggregateThenMaybeResetDoubles(
                   epochNanos,
                   attributes,
                   sum,
-                  this.count > 0,
-                  this.min,
-                  this.count > 0,
-                  this.max,
+                  recordMinMax && this.count > 0,
+                  recordMinMax ? this.min : 0,
+                  recordMinMax && this.count > 0,
+                  recordMinMax ? this.max : 0,
                   boundaryList,
                   counts,
                   exemplars);
@@ -195,8 +205,10 @@ protected void doRecordDouble(double value) {
 
       synchronized (lock) {
         this.sum += value;
-        this.min = Math.min(this.min, value);
-        this.max = Math.max(this.max, value);
+        if (recordMinMax) {
+          this.min = Math.min(this.min, value);
+          this.max = Math.max(this.max, value);
+        }
         this.count++;
         this.counts[bucketIndex]++;
       }