From 8dbba8dc0c8d51d18e639c96bd15acc0483c9504 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Nov 2021 09:27:23 -0800 Subject: [PATCH 1/3] Metrics SDK - consolidate the aggregation/aggregator term --- specification/metrics/sdk.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 3f2b779d70d..ed0458c2fb4 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -387,9 +387,9 @@ This Aggregation informs the SDK to collect: #### Histogram Aggregation -The Histogram Aggregation informs the SDK to select the best -Histogram Aggregation available. -i.e. [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregation). +The Histogram Aggregation informs the SDK to select the best Histogram +Aggregation available. i.e. [Explicit Bucket Histogram +Aggregation](./sdk.md#explicit-bucket-histogram-aggregation). This Aggregation does not have any configuration parameters. @@ -406,8 +406,8 @@ 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.

The Default Value represents the following buckets:
(-∞, 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, +∞) | | RecordMinMax | true, false | true | Whether to record min and max. | -Note: This aggregator should not fill out `sum` when used with instruments -that record negative measurements, e.g. `UpDownCounter` or `ObservableGauge`. +Note: This aggregation should not fill out `sum` when used with instruments that +record negative measurements, e.g. `UpDownCounter` or `ObservableGauge`. This Aggregation informs the SDK to collect: @@ -440,12 +440,15 @@ information: A Metric SDK MUST provide a mechanism to sample `Exemplar`s from measurements. -A Metric SDK MUST allow `Exemplar` sampling to be disabled. In this instance the SDK SHOULD not have overhead related to exemplar sampling. +A Metric SDK MUST allow `Exemplar` sampling to be disabled. In this instance +the SDK SHOULD not have overhead related to exemplar sampling. -A Metric SDK MUST sample `Exemplar`s only from measurements within the context of a sampled trace BY DEFAULT. +A Metric SDK MUST sample `Exemplar`s only from measurements within the context +of a sampled trace BY DEFAULT. -A Metric SDK MUST allow exemplar sampling to leverage the configuration of a metric aggregator. -For example, Exemplar sampling of histograms should be able to leverage bucket boundaries. +A Metric SDK MUST allow exemplar sampling to leverage the configuration of a +metric aggregation. For example, Exemplar sampling of histograms should be able +to leverage bucket boundaries. A Metric SDK SHOULD provide extensible hooks for Exemplar sampling, specifically: @@ -507,14 +510,14 @@ The SDK will come with two types of built-in exemplar reservoirs: 1. SimpleFixedSizeExemplarReservoir 2. AlignedHistogramBucketExemplarReservoir -By default, explicit bucket histogram aggregators with more than 1 bucket will -use `AlignedHistogramBucketExemplarReservoir`. All other aggregators will -use `SimpleFixedSizeExemplarReservoir`. +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) +*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) ``` bucket = random_integer(0, num_measurements_seen) From 7112cd57a572fe465c0fb86f40b3e5ecf0c88d53 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 23 Nov 2021 09:36:06 -0800 Subject: [PATCH 2/3] add a note to reserve aggregator term --- specification/metrics/sdk.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index ed0458c2fb4..4a51653dfc5 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -277,6 +277,10 @@ informs the SDK on the ways and means to compute [Aggregated Metrics](./datamodel.md#opentelemetry-protocol-data-model) from incoming Instrument [Measurements](./api.md#measurement). +Note: the term _aggregation_ is used instead of _aggregator_. It is recommended +that implementors reserve the "aggregator" term for the future when the SDK +allows custom aggregation implementations. + An `Aggregation` specifies an operation (i.e. [decomposable aggregate function](https://en.wikipedia.org/wiki/Aggregate_function#Decomposable_aggregate_functions) like Sum, Histogram, Min, Max, Count) From ea50d0bdd882f334d4b81c55bcb5c03c73e9fc76 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 24 Nov 2021 15:46:22 -0800 Subject: [PATCH 3/3] rewrap --- specification/metrics/sdk.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 4a51653dfc5..e0e201094dd 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -518,9 +518,10 @@ 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 +*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) ```