From 3c62dc86c5a37f9e4661288059c72bf3f07abfd1 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Fri, 1 Oct 2021 14:39:01 -0500 Subject: [PATCH 1/9] Incorporate histogram min and max fields into histogram language, add zero bucket histogram aggregation --- specification/metrics/sdk.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b67a478517b..7fea4867f36 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -301,6 +301,7 @@ The SDK MUST provide the following `Aggregation` to support the - [Last Value](./sdk.md#last-value-aggregation) - [Histogram](./sdk.md#histogram-aggregation) - [Explicit Bucket Histogram](./sdk.md#explicit-bucket-histogram-aggregation) +- [Zero Bucket Histogram](./sdk.md#zero-bucket-histogram-aggregation) #### None Aggregation @@ -388,12 +389,33 @@ This Aggregation honors the following configuration parameters: | Temporality | Delta, Cumulative | Cumulative | See [Temporality](./datamodel.md#temporality). | | 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, +∞) | -\[1\]: Language implementations may choose the best strategy for handling errors. (i.e. Log, Discard, etc...) - This Aggregation informs the SDK to collect: - Count of `Measurement` values falling within explicit bucket boundaries. - Arithmetic sum of `Measurement` values in population. +- Min `Measurement` value in population. +- Max `Measurement` value in population. + +#### Zero Bucket Histogram Aggregation + +The Zero Bucket Aggregation informs the SDK to collect data for +the [Histogram Metric Point](./datamodel.md#histogram) using zero buckets. This +produces lightweight histogram data points which capture the min, max, sum, and +count of a population of measurements. + +| Key | Value | Default Value | Description | +| --- | --- | --- | --- | +| Monotonic | boolean | true | if true, non-positive values are treated as errors1. | +| Temporality | Delta, Cumulative | Cumulative | See [Temporality](./datamodel.md#temporality). | + +This Aggregation informs the SDK to collect: + +- Count of `Measurement` values in population +- Arithmetic sum of `Measurement` values in population. +- Min `Measurement` value in population. +- Max `Measurement` value in population. + +\[1\]: Language implementations may choose the best strategy for handling errors. (i.e. Log, Discard, etc...) ## Attribute limits From e4b79593868908ce5c4c28999c728f35e1abe617 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Fri, 1 Oct 2021 17:13:40 -0500 Subject: [PATCH 2/9] Change default aggregation temporality to Delta --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7fea4867f36..a1eb987a45a 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -406,7 +406,7 @@ count of a population of measurements. | Key | Value | Default Value | Description | | --- | --- | --- | --- | | Monotonic | boolean | true | if true, non-positive values are treated as errors1. | -| Temporality | Delta, Cumulative | Cumulative | See [Temporality](./datamodel.md#temporality). | +| Temporality | Delta, Cumulative | Delta | See [Temporality](./datamodel.md#temporality). | This Aggregation informs the SDK to collect: From edc9936295d013ee011a25775f55531e3e4d2237 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Mon, 4 Oct 2021 14:56:25 -0500 Subject: [PATCH 3/9] Rename zero bucket histogram to degenerate histogram --- CHANGELOG.md | 3 ++- specification/metrics/sdk.md | 6 +++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 959aec0a195..2a2ef5c8fb4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,8 @@ release. ### Metrics - Add optional min / max fields to histogram data model. - ([#1915](https://github.com/open-telemetry/opentelemetry-specification/pull/1915)) + ([#1915](https://github.com/open-telemetry/opentelemetry-specification/pull/1915), + [#1983](https://github.com/open-telemetry/opentelemetry-specification/pull/1983)) ### Logs diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index a1eb987a45a..131e287132c 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -301,7 +301,7 @@ The SDK MUST provide the following `Aggregation` to support the - [Last Value](./sdk.md#last-value-aggregation) - [Histogram](./sdk.md#histogram-aggregation) - [Explicit Bucket Histogram](./sdk.md#explicit-bucket-histogram-aggregation) -- [Zero Bucket Histogram](./sdk.md#zero-bucket-histogram-aggregation) +- [Degenerate Histogram](./sdk.md#degenerate-histogram-aggregation) #### None Aggregation @@ -396,9 +396,9 @@ This Aggregation informs the SDK to collect: - Min `Measurement` value in population. - Max `Measurement` value in population. -#### Zero Bucket Histogram Aggregation +#### Degenerate Histogram Aggregation -The Zero Bucket Aggregation informs the SDK to collect data for +The Degenerate Histogram Aggregation informs the SDK to collect data for the [Histogram Metric Point](./datamodel.md#histogram) using zero buckets. This produces lightweight histogram data points which capture the min, max, sum, and count of a population of measurements. From 873395adce9a9411b2cf009d5d172056796b1ca4 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Fri, 8 Oct 2021 10:09:52 -0500 Subject: [PATCH 4/9] Remove monotonic parameter from histgoram aggregation, rename degenerate histogram to trivial histogram --- specification/metrics/sdk.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 131e287132c..d2c696e7081 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -301,7 +301,7 @@ The SDK MUST provide the following `Aggregation` to support the - [Last Value](./sdk.md#last-value-aggregation) - [Histogram](./sdk.md#histogram-aggregation) - [Explicit Bucket Histogram](./sdk.md#explicit-bucket-histogram-aggregation) -- [Degenerate Histogram](./sdk.md#degenerate-histogram-aggregation) +- [Trivial Histogram](./sdk.md#Trivial-histogram-aggregation) #### None Aggregation @@ -385,7 +385,6 @@ This Aggregation honors the following configuration parameters: | Key | Value | Default Value | Description | | --- | --- | --- | --- | -| Monotonic | boolean | true | if true, non-positive values are treated as errors1. | | Temporality | Delta, Cumulative | Cumulative | See [Temporality](./datamodel.md#temporality). | | 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, +∞) | @@ -396,27 +395,27 @@ This Aggregation informs the SDK to collect: - Min `Measurement` value in population. - Max `Measurement` value in population. -#### Degenerate Histogram Aggregation +#### Trivial Histogram Aggregation -The Degenerate Histogram Aggregation informs the SDK to collect data for -the [Histogram Metric Point](./datamodel.md#histogram) using zero buckets. This -produces lightweight histogram data points which capture the min, max, sum, and -count of a population of measurements. +The Trivial Histogram Aggregation informs the SDK to collect data for +the [Histogram Metric Point](./datamodel.md#histogram) using a single bucket +with boundaries (-∞, +∞). This produces lightweight histogram data +points which capture the min, max, sum and count of a population of +measurements. + +This Aggregation honors the following configuration parameters: | Key | Value | Default Value | Description | | --- | --- | --- | --- | -| Monotonic | boolean | true | if true, non-positive values are treated as errors1. | | Temporality | Delta, Cumulative | Delta | See [Temporality](./datamodel.md#temporality). | This Aggregation informs the SDK to collect: -- Count of `Measurement` values in population +- Count of `Measurement` values in population. - Arithmetic sum of `Measurement` values in population. - Min `Measurement` value in population. - Max `Measurement` value in population. -\[1\]: Language implementations may choose the best strategy for handling errors. (i.e. Log, Discard, etc...) - ## Attribute limits Attributes which belong to Metrics are exempt from the @@ -508,9 +507,9 @@ The SDK will come with two types of built-in exemplar reservoirs: 1. SimpleFixedSizeExemplarReservoir 2. AlignedHistogramBucketExemplarReservoir -By default, fixed sized histogram aggregators will use -`AlignedHistogramBucketExemplarReservoir` and all other aggregaators will use -`SimpleFixedSizeExemplarReservoir`. +By default, explicit bucket histogram aggregators, except trivial histogram +aggregators, will use `AlignedHistogramBucketExemplarReservoir`. All other +aggregators will use `SimpleFixedSizeExemplarReservoir`. *SimpleExemplarReservoir* This Exemplar reservoir MAY take a configuration parameter for the size of From 24f52798a92e2452afaf77df109c4c623a8b806b Mon Sep 17 00:00:00 2001 From: jack-berg Date: Fri, 8 Oct 2021 17:57:07 -0500 Subject: [PATCH 5/9] Adjust language on exemplar resevoir selection --- specification/metrics/sdk.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index d2c696e7081..81c81b07253 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -507,9 +507,9 @@ The SDK will come with two types of built-in exemplar reservoirs: 1. SimpleFixedSizeExemplarReservoir 2. AlignedHistogramBucketExemplarReservoir -By default, explicit bucket histogram aggregators, except trivial histogram -aggregators, will use `AlignedHistogramBucketExemplarReservoir`. All other -aggregators will use `SimpleFixedSizeExemplarReservoir`. +By default, explicit bucket histogram aggregators with more than 1 bucket will +use `AlignedHistogramBucketExemplarReservoir`. All other aggregators will +use `SimpleFixedSizeExemplarReservoir`. *SimpleExemplarReservoir* This Exemplar reservoir MAY take a configuration parameter for the size of From 219642d77ed82499d95182c1b701071c670d3936 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Tue, 12 Oct 2021 18:12:31 -0500 Subject: [PATCH 6/9] Fix type in anchor --- specification/metrics/sdk.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 81c81b07253..58f68df826c 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -301,7 +301,8 @@ The SDK MUST provide the following `Aggregation` to support the - [Last Value](./sdk.md#last-value-aggregation) - [Histogram](./sdk.md#histogram-aggregation) - [Explicit Bucket Histogram](./sdk.md#explicit-bucket-histogram-aggregation) -- [Trivial Histogram](./sdk.md#Trivial-histogram-aggregation) +- [Trivial Histogram](./sdk.md#trivial-histogram-aggregation) + #### None Aggregation From 121e739399fd433410f11928f815156081611adc Mon Sep 17 00:00:00 2001 From: jack-berg Date: Wed, 13 Oct 2021 14:04:06 -0500 Subject: [PATCH 7/9] Remove extra line --- specification/metrics/sdk.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 58f68df826c..e88bd8a2ef2 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -303,7 +303,6 @@ The SDK MUST provide the following `Aggregation` to support the - [Explicit Bucket Histogram](./sdk.md#explicit-bucket-histogram-aggregation) - [Trivial Histogram](./sdk.md#trivial-histogram-aggregation) - #### None Aggregation The None Aggregation informs the SDK to ignore/drop all Instrument Measurements From e2f6e1c9aa34c2afa8260e2e253de863fd72fab0 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Tue, 19 Oct 2021 10:49:00 -0500 Subject: [PATCH 8/9] Remove trivial histogram aggregation --- specification/metrics/sdk.md | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7c7e0b9ccec..062afbeff8b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -302,7 +302,6 @@ The SDK MUST provide the following `Aggregation` to support the - [Last Value](./sdk.md#last-value-aggregation) - [Histogram](./sdk.md#histogram-aggregation) - [Explicit Bucket Histogram](./sdk.md#explicit-bucket-histogram-aggregation) -- [Trivial Histogram](./sdk.md#trivial-histogram-aggregation) #### None Aggregation @@ -397,30 +396,6 @@ This Aggregation informs the SDK to collect: Note: This aggregator should not fill out `sum` when used with instruments that record negative measurements, e.g. `UpDownCounter` or `ObservableGauge`. -#### Trivial Histogram Aggregation - -The Trivial Histogram Aggregation informs the SDK to collect data for -the [Histogram Metric Point](./datamodel.md#histogram) using a single bucket -with boundaries (-∞, +∞). This produces lightweight histogram data -points which capture the min, max, sum and count of a population of -measurements. - -This Aggregation honors the following configuration parameters: - -| Key | Value | Default Value | Description | -| --- | --- | --- | --- | -| Temporality | Delta, Cumulative | Delta | See [Temporality](./datamodel.md#temporality). | - -This Aggregation informs the SDK to collect: - -- Count of `Measurement` values in population. -- Arithmetic sum of `Measurement` values in population. -- Min `Measurement` value in population. -- Max `Measurement` value in population. - -Note: This aggregator should not fill out `sum` when used with instruments -that record negative measurements, e.g. `UpDownCounter` or `ObservableGauge`. - ## Attribute limits Attributes which belong to Metrics are exempt from the From 620fc31a87300709dc1fd4df1dfa37db44a154ad Mon Sep 17 00:00:00 2001 From: jack-berg Date: Tue, 19 Oct 2021 13:18:09 -0500 Subject: [PATCH 9/9] Add RecordMinMax to Explicit Bucket Histogram --- specification/metrics/sdk.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 062afbeff8b..4d1674197f0 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -385,16 +385,17 @@ This Aggregation honors the following configuration parameters: | --- | --- | --- | --- | | Temporality | Delta, Cumulative | Cumulative | See [Temporality](./datamodel.md#temporality). | | 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`. This Aggregation informs the SDK to collect: - Count of `Measurement` values falling within explicit bucket boundaries. - Arithmetic sum of `Measurement` values in population. -- Min `Measurement` value in population. -- Max `Measurement` value in population. - -Note: This aggregator should not fill out `sum` when used with instruments -that record negative measurements, e.g. `UpDownCounter` or `ObservableGauge`. +- Min (optional) `Measurement` value in population. +- Max (optional) `Measurement` value in population. ## Attribute limits