diff --git a/CHANGELOG.md b/CHANGELOG.md index 2828457717e..b96286d8a3c 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 6237a54f6f0..98dfa5deff0 100644 --- a/specification/metrics/sdk.md +++ b/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