Specify optional Exponential Histogram Aggregation, add example code in the data model

CHANGELOG.md

@@ -31,6 +31,8 @@ release.
   ([#2210](https://github.com/open-telemetry/opentelemetry-specification/pull/2210))
 - Use UCUM units in Metrics Semantic Conventions.
   ([#2199](https://github.com/open-telemetry/opentelemetry-specification/pull/2199))
+- Specify optional support for an Exponential Histogram Aggregation.
+  ([#2252](https://github.com/open-telemetry/opentelemetry-specification/pull/2252))
 
 ### Logs
 

specification/metrics/datamodel.md

@@ -622,6 +622,21 @@ func GetExponent(value float64) int32 {
 }
 ```
 
+Implementations are permitted to round subnormal values up to the
+smallest normal value, which may permit the use of a built-in function:
+
+```golang
+
+func GetExponent(value float64) int {
+    // Note: Frexp() rounds submnormal values to the smallest normal
+    // value and returns an exponent corresponding to fractions in the
+    // range [0.5, 1), whereas we want [1, 2), so subtract 1 from the
+    // exponent.
+    _, exp := math.Frexp(value)
+    return exp - 1
+}
+```
+
 ##### Negative Scale: Extract and Shift the Exponent
 
 For negative scales, the index of a value equals the normalized
@@ -633,19 +648,57 @@ correct rounding for the negative indices.  This may be written as:
   return GetExponent(value) >> -scale
 ```
 
+The reverse mapping function is:
+
+```golang
+    return math.Ldexp(1, index << -scale)
+```
+
+Note that the reverse mapping function is expected to produce
+subnormal values even when the mapping function rounds them into
+normal values, since the lower boundary of the bucket containing the
+smallest normal value may be subnormal.  For example, at scale -4 the
+smallest normal value `0x1p-1022` falls into a bucket with lower
+boundary `0x1p-1024`.
+
 ##### All Scales: Use the Logarithm Function
 
-For any scale, use of the built-in natural logarithm
-function.  A multiplicative factor equal to `2**scale / ln(2)`
-proves useful (where `ln()` is the natural logarithm), for example:
+For any scale, the built-in natural logarithm function can be used to
+compute the bucket index.  A multiplicative factor equal to `2**scale
+/ ln(2)` proves useful (where `ln()` is the natural logarithm), for
+example:
 
 ```golang
-    scaleFactor := math.Log2E * math.Exp2(scale)
-    return int64(math.Floor(math.Log(value) * scaleFactor))
+    scaleFactor := math.Ldexp(math.Log2E, scale)
+    return math.Floor(math.Log(value) * scaleFactor)
 ```
 
 Note that in the example Golang code above, the built-in `math.Log2E`
-is defined as `1 / ln(2)`.
+is defined as the inverse natural logarithm of 2.
+
+The reverse mapping function is:
+
+```golang
+    inverseFactor := math.Ldexp(math.Ln2, -scale)
+    return math.Exp(index * inverseFactor), nil
+```
+
+Implementations should verify that their mapping function and inverse
+mapping function are correct near the lowest and highest IEEE floating
+point value.  In the Golang reference implementation, for example, the
+above formula computes `+Inf` for the maximum-index bucket.  In this
+case, it is appropriate to subtract `1<<scale` from the index and
+multiply the result by `2`.
+
+```golang
+    // Use this form in case the equation above computes +Inf
+    // as the lower boundary of a valid bucket.
+    inverseFactor := math.Ldexp(math.Ln2, -scale)
+    return 2.0 * math.Exp((index - (1 << scale)) * inverseFactor), nil
+```
+
+_Note that floating-point to integer type conversions have been
+omitted from the code fragments above, to improve readability._
 
 ##### Positive Scale: Use a Lookup Table
 

specification/metrics/sdk.md

@@ -18,7 +18,11 @@
     + [Sum Aggregation](#sum-aggregation)
     + [Last Value Aggregation](#last-value-aggregation)
     + [Histogram Aggregation](#histogram-aggregation)
+      - [Histogram Aggregation common behavior](#histogram-aggregation-common-behavior)
     + [Explicit Bucket Histogram Aggregation](#explicit-bucket-histogram-aggregation)
+    + [Exponential Histogram Aggregation](#exponential-histogram-aggregation)
+      - [Exponential Histogram Aggregation: Handle all normal values](#exponential-histogram-aggregation-handle-all-normal-values)
+      - [Exponential Histogram Aggregation: Maintain the ideal scale](#exponential-histogram-aggregation-maintain-the-ideal-scale)
 - [Attribute limits](#attribute-limits)
 - [Exemplar](#exemplar)
   * [ExemplarFilter](#exemplarfilter)
@@ -327,6 +331,10 @@ The SDK MUST provide the following `Aggregation` to support the
 - [Histogram](./sdk.md#histogram-aggregation)
 - [Explicit Bucket Histogram](./sdk.md#explicit-bucket-histogram-aggregation)
 
+The SDK MAY provide the following `Aggregation`:
+
+- [Exponential Histogram Aggregation](./sdk.md#exponential-histogram-aggregation)
+
 #### Drop Aggregation
 
 The Drop Aggregation informs the SDK to ignore/drop all Instrument Measurements
@@ -393,6 +401,19 @@ Aggregation](./sdk.md#explicit-bucket-histogram-aggregation).
 
 This Aggregation does not have any configuration parameters.
 
+##### Histogram Aggregation common behavior
+
+Histogram aggregations should not fill out `sum` when used with
+instruments that record negative measurements, e.g. `UpDownCounter` or
+`ObservableGauge`.
+
+All histogram Aggregations inform the SDK to collect:
+
+- Count of `Measurement` values in population.
+- Arithmetic sum of `Measurement` values in population.
+- Min (optional) `Measurement` value in population.
+- Max (optional) `Measurement` value in population.
+
 #### Explicit Bucket Histogram Aggregation
 
 The Explicit Bucket Histogram Aggregation informs the SDK to collect data for
@@ -406,15 +427,43 @@ This Aggregation honors the following configuration parameters:
 | Boundaries | double\[\] | [ 0, 5, 10, 25, 50, 75, 100, 250, 500, 1000 ] | Array of increasing values representing explicit bucket boundary values.<br><br>The Default Value represents the following buckets:<br>(-&infin;, 0], (0, 5.0], (5.0, 10.0], (10.0, 25.0], (25.0, 50.0], (50.0, 75.0], (75.0, 100.0], (100.0, 250.0], (250.0, 500.0], (500.0, 1000.0], (1000.0, +&infin;) |
 | RecordMinMax | true, false | true | Whether to record min and max. |
 
-Note: This aggregation should not fill out `sum` when used with instruments that
-record negative measurements, e.g. `UpDownCounter` or `ObservableGauge`.
+Explicit buckets are stated in terms of their upper boundary.  Buckets
+are exclusive of their lower boundary and inclusive of their upper
+bound (except at positive infinity).  A measurement is defined to fall
+into the least-numbered bucket with boundary that is greater than or
+equal to the measurement.
 
-This Aggregation informs the SDK to collect:
+#### Exponential Histogram Aggregation
 
-- Count of `Measurement` values falling within explicit bucket boundaries.
-- Arithmetic sum of `Measurement` values in population.
-- Min (optional) `Measurement` value in population.
-- Max (optional) `Measurement` value in population.
+The Exponential Histogram Aggregation informs the SDK to collect data
+for the [Exponential Histogram Metric
+Point](./datamodel.md#exponentialhistogram), which uses an exponential
+formula to determine bucket boundaries and an integer `scale`
+parameter to control resolution.
+
+This Aggregation honors the following configuration parameters:
+
+| Key                    | Value           | Default Value | Description                                                                                                                                                                                                                                     |
+| --                     | --              | --            | --                                                                                                                                                                                                                                              |
+| MaxSize                | integer         | 320           | Maximum number of buckets in each of the positive and negative ranges, not counting the special zero bucket.                                                                                                                                    |
+| RangeLimits (optional) | min, max double | _not set_     | When set, limit the range of positive measurements to the inclusive range [min, max] and limit the range of negative measurements to [-max, -min].  Paired with maximum size, this determines a fixed exponential scale during the constructor. |
+
+##### Exponential Histogram Aggregation: Handle all normal values
+
+When RangeLimits are not set, implementations are REQUIRED to handle
+the entire normal range of IEEE floating point values (i.e., all
+values except for +Inf, -Inf and NaN values).  Implementations are
+permitted to round subnormal values away from zero to the nearest
+normal value where it simplifies the implementation.
+
+##### Exponential Histogram Aggregation: Maintain the ideal scale
+
+Implementations SHOULD adjust the histogram scale as necessary to
+maintain the best resolution possible, given the maximum size.  This
+results in histogram Aggregations where at least one of the positive
+or negative ranges of buckets is more than half full, such that
+increasing scale by one would not be possible given the size
+constraint.
 
 ## Attribute limits