Add the Exponential Histogram Aggregator.

CHANGELOG.md

@@ -12,6 +12,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Add `ManualReader` struct in `go.opentelemetry.io/otel/sdk/metric`. (#4244)
 - Add `PeriodicReader` struct in `go.opentelemetry.io/otel/sdk/metric`. (#4244)
+- Add support for Exponential Histogram Aggregations. A Histogram can be configured as an Exponential Histogram using a view with the `go.opentelemetry.io/otel/sdk/metric/aggregation.ExponentialHistogram` as the aggregation. (#4245)
 - Add `Exporter` struct in `go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc`. (#4272)
 - Add `Exporter` struct in `go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp`. (#4272)
 - OTLP Metrics Exporter now supports the `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` environment variable. (#4287)

sdk/metric/aggregation/aggregation.go

@@ -164,3 +164,54 @@
 		NoMinMax:   h.NoMinMax,
 	}
 }
+
+// ExponentialHistogram is an aggregation that summarizes a set of
+// measurements as an histogram with bucket widths that grow exponentially.
+type ExponentialHistogram struct {
+	// MaxSize is the maximum number of buckets to use for the histogram.
+	MaxSize int
+	// MaxScale is the maximum resolution scale to use for the histogram.
+	MaxScale int
+
+	// NoMinMax indicates whether to not record the min and max of the
+	// distribution. By default, these extrema are recorded.
+	//
+	// Recording these extrema for cumulative data is expected to have little
+	// value, they will represent the entire life of the instrument instead of
+	// just the current collection cycle. It is recommended to set this to true
+	// for that type of data to avoid computing the low-value extrema.
+	NoMinMax bool
+}
+
+var _ Aggregation = ExponentialHistogram{}
+
+// private attempts to ensure no user-defined Aggregation is allowed. The
+// OTel specification does not allow user-defined Aggregation currently.
+func (e ExponentialHistogram) private() {}
+
+// Copy returns a deep copy of the Aggregation.
+func (e ExponentialHistogram) Copy() Aggregation {
+	return e
+}
+
+const (
+	expoMaxScale = 20
+	expoMinScale = -10
+)
+
+// errExpoHist is returned by misconfigured ExplicitBucketHistograms.
+var errExpoHist = fmt.Errorf("%w: explicit bucket histogram", errAgg)
+
+// Err returns an error for any misconfigured Aggregation.
+func (e ExponentialHistogram) Err() error {
+	if e.MaxScale < expoMinScale {
+		return fmt.Errorf("%w: max size %d is less than minimum scale %d", errExpoHist, e.MaxSize, expoMinScale)
+	}
+	if e.MaxScale > expoMaxScale {
+		return fmt.Errorf("%w: max size %d is greater than maximum scale %d", errExpoHist, e.MaxSize, expoMaxScale)
+	}
+	if e.MaxSize <= 0 {
+		return fmt.Errorf("%w: max size %d is less than or equal to zero", errExpoHist, e.MaxSize)
+	}
+	return nil
+}

sdk/metric/aggregation/aggregation_test.go

@@ -20,6 +20,13 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
+func defaultExponentialHistogram() ExponentialHistogram {
+	return ExponentialHistogram{
+		MaxSize:  160,
+		MaxScale: 20,
+	}
+}
+
 func TestAggregationErr(t *testing.T) {
 	t.Run("DropOperation", func(t *testing.T) {
 		assert.NoError(t, Drop{}.Err())
@@ -55,6 +62,35 @@ func TestAggregationErr(t *testing.T) {
 			Boundaries: []float64{0, 1, 2, 1, 3, 4},
 		}.Err(), errAgg)
 	})
+
+	t.Run("ExponentialHistogramOperation", func(t *testing.T) {
+		assert.NoError(t, defaultExponentialHistogram().Err())
+
+		assert.NoError(t, ExponentialHistogram{
+			MaxSize:  1,
+			NoMinMax: true,
+		}.Err())
+
+		assert.NoError(t, ExponentialHistogram{
+			MaxSize:  1024,
+			MaxScale: -3,
+		}.Err())
+	})
+
+	t.Run("InvalidExponentialHistogramOperation", func(t *testing.T) {
+		// MazSize must be greater than 0
+		assert.ErrorIs(t, ExponentialHistogram{}.Err(), errAgg)
+
+		// MaxScale Must be <=20 and >= -10
+		assert.ErrorIs(t, ExponentialHistogram{
+			MaxSize:  1,
+			MaxScale: 30,
+		}.Err(), errAgg)
+		assert.ErrorIs(t, ExponentialHistogram{
+			MaxSize:  1,
+			MaxScale: -20,
+		}.Err(), errAgg)
+	})
 }
 
 func TestExplicitBucketHistogramDeepCopy(t *testing.T) {

sdk/metric/internal/aggregate/aggregate.go

@@ -125,3 +125,22 @@
 		return len(hData.DataPoints)
 	}
 }
+
+// ExponentialBucketHistogram returns a histogram aggregate function input and
+// output.
+func (b Builder[N]) ExponentialBucketHistogram(cfg aggregation.ExponentialHistogram, noSum bool) (Measure[N], ComputeAggregation) {
+	var h aggregator[N]
+	switch b.Temporality {
+	case metricdata.DeltaTemporality:
+		h = newDeltaExponentialHistogram[N](cfg, noSum)
+	default:
+		h = newCumulativeExponentialHistogram[N](cfg, noSum)
+	}
+	return b.input(h), func(dest *metricdata.Aggregation) int {
+		// TODO (#4220): optimize memory reuse here.
+		*dest = h.Aggregation()
+
+		hData, _ := (*dest).(metricdata.ExponentialHistogram[N])
+		return len(hData.DataPoints)
+	}
+}