Revise the exemplar default reservoirs (open-telemetry#3627)

- Make it normative that an SDK is recommended to include both types of
default reservoirs.
- Make the description of both default reservoirs their own
sub-sections.
- Correct the "SimpleExemplarReservoir" section to be titled
"SimpleFixedSizeExemplarReservoir".
- Loosen the SimpleFixedSizeExemplarReservoir to allow any
uniformly-weighted sampling algorithm instead of just the naive one that
is not optimal.
- The current algorithm has an asymptotic running time of `O(n)`. There
are other sampling algorithms that produce equivalent results and have
more optimal asymptotic running times. Therefore, do not restrict
implementations to only implementing the inefficient algorithm.

CHANGELOG.md

@@ -15,6 +15,8 @@ release.
 
 - Add experimental metric attributes advice API.
   ([#3546](https://github.com/open-telemetry/opentelemetry-specification/pull/3546))
+- Revise the exemplar default reservoirs.
+  ([#3627](https://github.com/open-telemetry/opentelemetry-specification/pull/3627))
 
 ### Logs
 

specification/metrics/sdk.md

@@ -55,6 +55,8 @@ linkTitle: SDK
     + [TraceBased](#tracebased)
   * [ExemplarReservoir](#exemplarreservoir)
   * [Exemplar defaults](#exemplar-defaults)
+    + [SimpleFixedSizeExemplarReservoir](#simplefixedsizeexemplarreservoir)
+    + [AlignedHistogramBucketExemplarReservoir](#alignedhistogrambucketexemplarreservoir)
 - [MetricReader](#metricreader)
   * [MetricReader operations](#metricreader-operations)
     + [RegisterProducer(metricProducer)](#registerproducermetricproducer)
@@ -972,20 +974,21 @@ The `ExemplarReservoir` SHOULD avoid allocations when sampling exemplars.
 
 ### Exemplar defaults
 
-The SDK will come with two types of built-in exemplar reservoirs:
+The SDK SHOULD include two types of built-in exemplar reservoirs:
 
-1. SimpleFixedSizeExemplarReservoir
-2. AlignedHistogramBucketExemplarReservoir
+1. `SimpleFixedSizeExemplarReservoir`
+2. `AlignedHistogramBucketExemplarReservoir`
 
 By default, explicit bucket histogram aggregation with more than 1 bucket will
 use `AlignedHistogramBucketExemplarReservoir`. All other aggregations will use
 `SimpleFixedSizeExemplarReservoir`.
 
-_SimpleExemplarReservoir_
-This Exemplar reservoir MAY take a configuration parameter for the size of the
-reservoir pool.  The reservoir will accept measurements using an equivalent of
-the [naive reservoir sampling
-algorithm](https://en.wikipedia.org/wiki/Reservoir_sampling)
+#### SimpleFixedSizeExemplarReservoir
+
+This reservoir MUST use an uniformly-weighted sampling algorithm based on the
+number of samples the reservoir has seen so far to determine if the offered
+measurements should be sampled. For example, the [simple reservoir sampling
+algorithm](https://en.wikipedia.org/wiki/Reservoir_sampling) can be used:
 
   ```
   bucket = random_integer(0, num_measurements_seen)
@@ -994,10 +997,15 @@ algorithm](https://en.wikipedia.org/wiki/Reservoir_sampling)
   end
   ```
 
-Additionally, the `num_measurements_seen` count SHOULD be reset at every
-collection cycle.
+Any stateful portion of sampling computation SHOULD be reset every collection
+cycle. For the above example, that would mean that the `num_measurements_seen`
+count is reset every time the reservoir is collected.
+
+This Exemplar reservoir MAY take a configuration parameter for the size of the
+reservoir pool.
+
+#### AlignedHistogramBucketExemplarReservoir
 
-_AlignedHistogramBucketExemplarReservoir_
 This Exemplar reservoir MUST take a configuration parameter that is the
 configuration of a Histogram.  This implementation MUST keep the last seen
 measurement that falls within a histogram bucket.  The reservoir will accept