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)
 
 ### Changed
 

sdk/metric/aggregation/aggregation.go

@@ -164,3 +164,65 @@
 		NoMinMax:   h.NoMinMax,
 	}
 }
+
+// ExponentialHistogram is an aggregation that summarizes a set of
+// measurements as an histogram with buckets 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
+	// ZeroThreshold sets the minimum value blow which will be recorded as zero.
+	ZeroThreshold float64
+
+	// 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
+}
+
+// DefaultExponentialHistogram returns the default Exponential Histogram aggregation.
+func DefaultExponentialHistogram() ExponentialHistogram {
+	return ExponentialHistogram{
+		MaxSize:       160,
+		MaxScale:      20,
+		ZeroThreshold: 0.0,
+	}
+}
+
+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

@@ -55,6 +55,36 @@ 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,
+			ZeroThreshold: 1.0,
+		}.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/aggregator_example_test.go

@@ -84,6 +84,23 @@ func (p *meter) Int64Histogram(string, ...metric.Int64HistogramOption) (metric.I
 	return hist, nil
 }
 
+func (p *meter) Int64ExponentialHistogram(string, ...metric.Int64HistogramOption) (metric.Int64Histogram, error) {
+	// This is an example of how a meter would create an aggregator for a new
+	// histogram. At this point the provider would determine the aggregation
+	// and temporality to used based on the Reader and View configuration.
+	// Assume here these are determined to be a delta explicit-bucket
+	// histogram.
+
+	aggregator := NewDeltaExponentialHistogram[int64](aggregation.DefaultExponentialHistogram())
+	hist := inst{aggregateFunc: aggregator.Aggregate}
+
+	p.aggregations = append(p.aggregations, aggregator.Aggregation())
+
+	fmt.Printf("using %T aggregator for histogram\n", aggregator)
+
+	return hist, nil
+}
+
 // inst is a generalized int64 synchronous counter, up-down counter, and
 // histogram used for demonstration purposes only.
 type inst struct {
@@ -103,9 +120,11 @@ func Example() {
 	_, _ = m.Int64Counter("counter example")
 	_, _ = m.Int64UpDownCounter("up-down counter example")
 	_, _ = m.Int64Histogram("histogram example")
+	_, _ = m.Int64ExponentialHistogram("exponential histogram example")
 
 	// Output:
 	// using *internal.cumulativeSum[int64] aggregator for counter
 	// using *internal.lastValue[int64] aggregator for up-down counter
 	// using *internal.deltaHistogram[int64] aggregator for histogram
+	// using *internal.deltaExponentialHistogram[int64] aggregator for histogram
 }