From 867127b2ff83e74c9e4f6aa28e39ba6f583b9166 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 22 Sep 2021 09:44:22 -0700 Subject: [PATCH 1/7] Add concurrency/compatibilty requirements to the Metrics SDK, fix the missing MetricReader.Shutdown --- specification/metrics/api.md | 6 ++-- specification/metrics/sdk.md | 54 ++++++++++++++++++++++++++++++++---- 2 files changed, 53 insertions(+), 7 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 1fefb5e4a25..8118a11e5f3 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -32,6 +32,8 @@ Table of Contents * [Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation) * [Asynchronous UpDownCounter operations](#asynchronous-updowncounter-operations) * [Measurement](#measurement) +* [Compatibility requirements](#compatibility-requirements) +* [Concurrency requirements](#concurrency-requirements) @@ -978,7 +980,7 @@ for the interaction between the API and SDK. * A value * [`Attributes`](../common/common.md#attributes) -## Compatibility +## Compatibility requirements All the metrics components SHOULD allow new APIs to be added to existing components without introducing breaking changes. @@ -986,7 +988,7 @@ components without introducing breaking changes. All the metrics APIs SHOULD allow optional parameter(s) to be added to existing APIs without introducing breaking changes. -## Concurrency +## Concurrency requirements For languages which support concurrent execution the Metrics APIs provide specific guarantees and safeties. diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 3145bc52114..fb7ff92b282 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -8,17 +8,19 @@ Table of Contents * [MeterProvider](#meterprovider) -* [Attribute Limits](#attribute-limits) +* [Attribute limits](#attribute-limits) * [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) * [ExemplarReservoir](#exemplarreservoir) - * [Exemplar Defaults](#exemplar-defaults) + * [Exemplar defaults](#exemplar-defaults) * [MetricReader](#metricreader) * [Periodic exporting MetricReader](#periodic-exporting-metricreader) * [MetricExporter](#metricexporter) * [Push Metric Exporter](#push-metric-exporter) * [Pull Metric Exporter](#pull-metric-exporter) -* [Defaults and Configuration](#defaults-and-configuration) +* [Defaults and configuration](#defaults-and-configuration) +* [Compatibility requirements](#compatibility-requirements) +* [Concurrency requirements](#concurrency-requirements) @@ -393,7 +395,7 @@ This Aggregation informs the SDK to collect: - Count of `Measurement` values falling within explicit bucket boundaries. - Arithmetic sum of `Measurement` values in population. -## Attribute Limits +## Attribute limits Attributes which belong to Metrics are exempt from the [common rules of attribute limits](../common/common.md#attribute-limits) at this @@ -574,6 +576,22 @@ SDK](../overview.md#sdk) authors MAY choose to add parameters (e.g. callback, filter, timeout). [OpenTelemetry SDK](../overview.md#sdk) authors MAY choose the return value type, or do not return anything. +### Shutdown + +This method provides a way for the `MetricReader` to do any cleanup required. + +`Shutdown` MUST be called only once for each `MetricReader` instance. After the +call to `Shutdown`, subsequent invocations to `Collect` are not allowed. SDKs +SHOULD return some failure for these calls, if possible. + +`Shutdown` SHOULD provide a way to let the caller know whether it succeeded, +failed or timed out. + +`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` CAN be +implemented as a blocking API or an asynchronous API which notifies the caller +via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors CAN +decide if they want to make the shutdown timeout configurable. + ### Periodic exporting MetricReader This is an implementation of the `MetricReader` which collects metrics based on @@ -752,7 +770,7 @@ modeled to interact with other components in the SDK: +-----------------------------+ ``` -## Defaults and Configuration +## Defaults and configuration The SDK MUST provide the following configuration parameters for Exemplar sampling: @@ -766,3 +784,29 @@ Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are: - `"NONE"`: No measurements are eligble for exemplar sampling. - `"ALL"`: All measurements are eligible for exemplar sampling. - `"WITH_SAMPLED_TRACE"`: Only allow measurements with a sampled parent span in context. + +## Compatibility requirements + +All the metrics components SHOULD allow new methods to be added to existing +components without introducing breaking changes. + +All the metrics SDK methods SHOULD allow optional parameter(s) to be added to +existing methods without introducing breaking changes. + +## Concurrency requirements + +For languages which support concurrent execution the Metrics SDKs provide +specific guarantees and safeties. + +**MeterProvider** - Meter creation, `ForceFlush` and `Shutdown` are safe to be +called concurrently. + +**ExemplarFilter** - all methods are safe to be called concurrently. + +**ExemplarReservoir** - all methods are safe to be called concurrently. + +**MeterReader** - `Collect`, `ForceFlush` and `Shutdown` are safe to be called +concurrently. + +**MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called +concurrently. From c44430d31fe72d2681f82de3433039df73d719d0 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 22 Sep 2021 09:50:26 -0700 Subject: [PATCH 2/7] lowercase --- 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 fb7ff92b282..e0b8afcb757 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -479,7 +479,7 @@ from the original sample measurement. The `ExemplarReservoir` SHOULD avoid allocations when sampling exemplars. -### Exemplar Defaults +### Exemplar defaults The SDK will come with two types of built-in exemplar reservoirs: From 65220dbda7910fc2f12745d718151d916f649a3a Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 22 Sep 2021 23:51:31 -0700 Subject: [PATCH 3/7] update links --- specification/library-guidelines.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/library-guidelines.md b/specification/library-guidelines.md index ceff34e568a..dd837c08d91 100644 --- a/specification/library-guidelines.md +++ b/specification/library-guidelines.md @@ -132,5 +132,6 @@ guidelines on the performance expectations that API implementations should meet, Please refer to individual API specification for guidelines on what concurrency safeties should API implementations provide and how they should be documented: -* [Metrics API](./metrics/api.md#concurrency) +* [Metrics API](./metrics/api.md#concurrency-requirements) +* [Metrics SDK](./metrics/sdk.md#concurrency-requirements) * [Tracing API](./trace/api.md#concurrency) From 94ecf8f1a6d55fadfa0514044d92a850232f9e57 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 22 Sep 2021 23:56:12 -0700 Subject: [PATCH 4/7] fix typo --- specification/metrics/sdk.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index e0b8afcb757..dde79223ba6 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -805,8 +805,7 @@ called concurrently. **ExemplarReservoir** - all methods are safe to be called concurrently. -**MeterReader** - `Collect`, `ForceFlush` and `Shutdown` are safe to be called -concurrently. +**MetricReader** - `Collect` and `Shutdown` are safe to be called concurrently. **MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called concurrently. From b38e552c4a46335fe6baf1ec4628e724bb8e9d02 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 23 Sep 2021 09:57:19 -0700 Subject: [PATCH 5/7] Update specification/metrics/sdk.md Co-authored-by: Joshua MacDonald --- 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 dde79223ba6..2b076b9dd0b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -791,7 +791,7 @@ All the metrics components SHOULD allow new methods to be added to existing components without introducing breaking changes. All the metrics SDK methods SHOULD allow optional parameter(s) to be added to -existing methods without introducing breaking changes. +existing methods without introducing breaking changes, if possible. ## Concurrency requirements From cf39e8175c66fc0fcd6e8ae39521986f5cf378cb Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 23 Sep 2021 16:28:39 -0700 Subject: [PATCH 6/7] if possible --- specification/metrics/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 8118a11e5f3..3a86f9a5023 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -986,7 +986,7 @@ All the metrics components SHOULD allow new APIs to be added to existing components without introducing breaking changes. All the metrics APIs SHOULD allow optional parameter(s) to be added to existing -APIs without introducing breaking changes. +APIs without introducing breaking changes, if possible. ## Concurrency requirements From 8482c42cb0a0a3919b6c9b0a02267ab07b631956 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 29 Sep 2021 18:58:01 -0700 Subject: [PATCH 7/7] update changelog --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 465be6679d8..039817421e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,7 +30,8 @@ release. [#1888](https://github.com/open-telemetry/opentelemetry-specification/pull/1888), [#1912](https://github.com/open-telemetry/opentelemetry-specification/pull/1912), [#1913](https://github.com/open-telemetry/opentelemetry-specification/pull/1913), - [#1938](https://github.com/open-telemetry/opentelemetry-specification/pull/1938)) + [#1938](https://github.com/open-telemetry/opentelemetry-specification/pull/1938), + [#1958](https://github.com/open-telemetry/opentelemetry-specification/pull/1958)) ### Logs