From dc3d5ed00cc0debb52079060a576f0db7cc6955a Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 18 Jan 2022 12:23:36 -0800 Subject: [PATCH 1/4] allow duplicate instrument reg --- specification/metrics/api.md | 40 ++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index c5d75d81660..b2c8aa0d678 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -180,14 +180,33 @@ will have the following information: * An optional `unit` of measure * An optional `description` -Instruments are associated with the Meter during creation, and are identified by -the name: - -* Meter implementations MUST return an error when multiple Instruments are - registered under the same Meter instance using the same name. -* Different Meters MUST be treated as separate namespaces. The names of the - Instruments under one Meter SHOULD NOT interfere with Instruments under - another Meter. + + +Instruments are associated with the Meter during creation and are +identified by instrument name. Duplicate registration of +identically-named instruments within a Meter is treated as follows: + +* If the registration is semantically identical, meaning to have the + same `kind` and `unit` as a previously registered instrument of the + same `name`, the implementation MUST return a valid instrument. + It is unspecified whether or under which conditions the same or different + instrument instance will be returned as a result of duplicate registration. +* If the registration is semantically not identical, the + implementation MUST return a registration error to the user when the + instrument is constructed. + +When determining whether a duplicate registration is valid, +language-level features such the distinction between integer and +floating point numbers SHOULD be considered. Equivalently, +implementations SHOULD NOT support an application in emitting both +integer and floating point numbers for the same metric inside the same +instrumentation library. + + + +Different Meters MUST be treated as separate namespaces. The names of the +Instruments under one Meter SHOULD NOT interfere with Instruments under +another Meter. @@ -239,6 +258,11 @@ instrument. It MUST be treated as an opaque string from the API and SDK. * It MUST support at least 1023 characters. [OpenTelemetry API](../overview.md#api) authors MAY decide if they want to support more. +Note the `description` property of an instrument is explicitly +disregarded when considering duplicate registration, because it is not +semantic in nature. Implementations SHOULD use any of the provided +`description` values when emitting metrics that had duplicate registrations. + Instruments can be categorized based on whether they are synchronous or asynchronous: From 80c0e73d06b0510edb96979c3fe6e618ad2a24a7 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 18 Jan 2022 12:23:48 -0800 Subject: [PATCH 2/4] comment about single-writer rule and duplicate instruments --- specification/metrics/sdk.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f85f92b061b..4b091191931 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -952,3 +952,22 @@ called concurrently. **MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called concurrently. + +## Data model requirements + +The implementation is required to respect the OpenTelemetry Metrics +data model [Single Writer](datamodel.md#single-writer) requirement. +This rule stipulates that the implementation MUST avoid creating +duplicate output streams from a given SDK. + +This rule is the basis of the output-name uniqueness check in for +[Views](#view) above, and it also constrains how duplicate instrument +registration is handled. + +For example, the implementation is not required to return the +identical instrument when a duplicate instrument is registered, but +assuming it does allow separate instances to co-exist, the +implementation MUST eliminate the duplication at a later point using +the [natural merge function](#opentelemetry-protocol-data-model) for +those data points, as otherwise it would risk violating the +single-writer rule. From 64c955f81c6a90c6d9be0f008900d3100ff25936 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 18 Jan 2022 12:30:36 -0800 Subject: [PATCH 3/4] comment about duplicate asynchronous observations --- specification/metrics/api.md | 10 ++++++++++ specification/metrics/sdk.md | 5 +++++ 2 files changed, 15 insertions(+) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index b2c8aa0d678..7267e279cfc 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -288,6 +288,16 @@ Please note that the term _synchronous_ and _asynchronous_ have nothing to do with the [asynchronous pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation). +When asynchronous instruments are used with duplicate registrations, +meaning to have more than one callback provided, the order of callback +execution is unspecified. Callers SHOULD avoid making duplicate +observations from asynchronous instrument callbacks. However, if a +user accidentally makes duplicate observations, meaning to provide +more than one value for a given asynchronous instrument and attribute +set, the caller SHOULD expect the last-observed value to be the one +recorded. This is sometimes referred to as "last-value wins" for +asynchronous instruments. + ### Counter `Counter` is a [synchronous Instrument](#synchronous-instrument) which supports diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 4b091191931..945306d4c17 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -971,3 +971,8 @@ implementation MUST eliminate the duplication at a later point using the [natural merge function](#opentelemetry-protocol-data-model) for those data points, as otherwise it would risk violating the single-writer rule. + +As another example, users are encouraged not to make duplicate +observations from asynchronous instrument callbacks. However, +implementations MUST NOT violate the single-writer rule even when +users make duplicate observations. From e70203c2d4e275337b8b54b1d6aa4bbdd6f2241f Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 18 Jan 2022 12:34:26 -0800 Subject: [PATCH 4/4] refer to supp guidelines as well --- specification/metrics/sdk.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 945306d4c17..6825a5aa0ca 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -975,4 +975,6 @@ single-writer rule. As another example, users are encouraged not to make duplicate observations from asynchronous instrument callbacks. However, implementations MUST NOT violate the single-writer rule even when -users make duplicate observations. +users make duplicate observations. This is also covered in the +[supplemental guidelines for handling asynchronous instrument +views](#asynchronous-example-attribute-removal-in-a-view).