From 16da729707e02e83f3a1b25b4faa3094c3f9e29b Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 30 Sep 2021 06:59:58 -0700 Subject: [PATCH] Multiple improvements to the Metrics SDK (#1958) * Added concurrency/compatibility requirements section in the Metrics SDK * Added MetricReader.Shutdown * Updated the ToC --- CHANGELOG.md | 3 +- specification/library-guidelines.md | 3 +- specification/metrics/api.md | 8 ++-- specification/metrics/sdk.md | 58 +++++++++++++++++++++++++---- 4 files changed, 60 insertions(+), 12 deletions(-) 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 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) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 1fefb5e4a25..3a86f9a5023 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,15 +980,15 @@ 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. 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 +## 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 2862383297e..b67a478517b 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 @@ -477,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: @@ -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,6 +770,32 @@ modeled to interact with other components in the SDK: +-----------------------------+ ``` -## Defaults and Configuration +## Defaults and configuration + +The SDK MUST provide configuration according to the [SDK environment +variables](../sdk-environment-variables.md) specification. + +## 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, if possible. + +## 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. + +**MetricReader** - `Collect` and `Shutdown` are safe to be called concurrently. -The SDK MUST provide configuration according to the [SDK environment variables](../sdk-environment-variables.md) specification. +**MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called +concurrently.