From 7c5143e20e105a72e774e66f9edf3469b25ac794 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 17 Jul 2023 14:13:15 -0700 Subject: [PATCH 1/7] Specify how to handle instrument name conflicts Resolves #3539 --- specification/metrics/sdk.md | 66 +++++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 95d228e6c47..c3232b9b9be 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -42,6 +42,7 @@ linkTitle: SDK + [Asynchronous instrument cardinality limits](#asynchronous-instrument-cardinality-limits) - [Meter](#meter) * [Duplicate instrument registration](#duplicate-instrument-registration) + + [Name conflict](#name-conflict) * [Instrument name](#instrument-name) * [Instrument unit](#instrument-unit) * [Instrument description](#instrument-description) @@ -768,40 +769,57 @@ Distinct meters MUST be treated as separate namespaces for the purposes of detec ### Duplicate instrument registration -When more than one Instrument of the same `name` is created for identical -Meters from the same MeterProvider, denoted _duplicate instrument -registration_, the Meter MUST create a valid Instrument in every case. Here, -"valid" means an instrument that is functional and can be expected to export -data, despite potentially creating a [semantic error in the data -model](data-model.md#opentelemetry-protocol-data-model-producer-recommendations). - -It is unspecified whether or under which conditions the same or -different Instrument instance will be returned as a result of -duplicate instrument registration. The term _identical_ applied to -Instruments describes instances where all [identifying -fields](./api.md#instrument) are equal. The term _distinct_ applied -to Instruments describes instances where at least one field value is -different. +A _duplicate instrument registration_ occurs when more than one Instrument of +the same [`name`](./api.md#instrument-name-syntax) is created for identical +Meters from the same MeterProvider but they have different [identifying +fields](./api.md#instrument). -To accomidate [the recommendations from the data -model](data-model.md#opentelemetry-protocol-data-model-producer-recommendations), -the SDK MUST aggregate data from [identical Instruments](api.md#instrument) -together in its export pipeline. +Whenever this occurs, users still need to be able to make measurements with the +duplicate instrument. This means that the Meter MUST return a functional +instrument that can be expected to export data even if this will cause +[semantic error in the data +model](data-model.md#opentelemetry-protocol-data-model-producer-recommendations). -When a duplicate instrument registration occurs, and it is not corrected with a -View, a warning SHOULD be emitted. The emitted warning SHOULD include -information for the user on how to resolve the conflict, if possible. +Additionally, users need to be informed about this error. Therefore, when a +duplicate instrument registration occurs, and it is not corrected with a View, +a warning SHOULD be emitted. The emitted warning SHOULD include information for +the user on how to resolve the conflict, if possible. 1. If the potential conflict involves multiple `description` properties, setting the `description` through a configured View SHOULD avoid the warning. -2. If the potential conflict involves instruments that can be - distinguished by a supported View selector (e.g., instrument type) - a renaming View recipe SHOULD be included in the warning. +2. If the potential conflict involves instruments that can be distinguished by + a supported View selector (e.g. name, instrument kind) a renaming View + recipe SHOULD be included in the warning. 3. Otherwise (e.g., use of multiple units), the SDK SHOULD pass through the data by reporting both `Metric` objects and emit a generic warning describing the duplicate instrument registration. +Outside of the following [sub-section](#name-conflict), it is unspecified +whether or under which conditions the same or different Instrument instance +will be returned as a result of duplicate instrument registration. The term +_identical_ applied to Instruments describes instances where all [identifying +fields](./api.md#instrument) are equal. The term _distinct_ applied to +Instruments describes instances where at least one field value is different. + +To accommodate [the recommendations from the data +model](data-model.md#opentelemetry-protocol-data-model-producer-recommendations), +the SDK MUST aggregate data from [identical Instruments](api.md#instrument) +together in its export pipeline. + +#### Name conflict + +The [`name`](./api.md#instrument-name-syntax) of an Instrument is defined to be +case-insensitive. If an SDK uses a case-sensitive encoding to represent this +`name`, a duplicate instrument registration will occur when a user passes +multiple casings of the same `name`. + +If a duplicate instrument registration occurs due to an Instrument name +conflict, the Meter MUST return distinct instruments for each casing and log an +appropriate error as described above. Unifying of the names is expected to be +better handled "downstream" in an exporter or collection system that will have +better context for how to handle the conflict. + ### Instrument name When a Meter creates an instrument, it SHOULD validate the instrument name From 0e4b5abd101f5654eb7705bb72e7d25814a44f61 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 17 Jul 2023 14:17:29 -0700 Subject: [PATCH 2/7] Add changelog entry --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f46e7f8bae0..44758ad328c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ release. ### Metrics +- Specify how to handle instrument name conflicts. + ([#3606](/~https://github.com/open-telemetry/opentelemetry-specification/pull/3606)) + ### Logs ### Resource From 989df97129fc7c7031242482251b45b4dae59003 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 19 Jul 2023 11:17:24 -0700 Subject: [PATCH 3/7] Merge paragraphs --- specification/metrics/sdk.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 3e115454a7d..f19b37085b4 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -812,13 +812,11 @@ together in its export pipeline. The [`name`](./api.md#instrument-name-syntax) of an Instrument is defined to be case-insensitive. If an SDK uses a case-sensitive encoding to represent this `name`, a duplicate instrument registration will occur when a user passes -multiple casings of the same `name`. - -If a duplicate instrument registration occurs due to an Instrument name -conflict, the Meter MUST return distinct instruments for each casing and log an -appropriate error as described above. Unifying of the names is expected to be -better handled "downstream" in an exporter or collection system that will have -better context for how to handle the conflict. +multiple casings of the same `name`. When this happens, the Meter MUST return +distinct instruments for each casing and log an appropriate error as described +above. Unifying of the names is expected to be better handled "downstream" in +an exporter or collection system that will have better context for how to +handle the conflict. ### Instrument name From ce99cf4f7953e381e1173f084a035b4655587d34 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 26 Jul 2023 12:26:47 -0700 Subject: [PATCH 4/7] Pivot to first-seen --- specification/metrics/sdk.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 6087c216ccd..0d816abbf30 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -813,10 +813,14 @@ The [`name`](./api.md#instrument-name-syntax) of an Instrument is defined to be case-insensitive. If an SDK uses a case-sensitive encoding to represent this `name`, a duplicate instrument registration will occur when a user passes multiple casings of the same `name`. When this happens, the Meter MUST return -distinct instruments for each casing and log an appropriate error as described -above. Unifying of the names is expected to be better handled "downstream" in -an exporter or collection system that will have better context for how to -handle the conflict. +an instrument using the first-seen instrument name and log an appropriate error +as described above. + +For example, if a user creates an instrument with the name `requestCount` and +then makes another request to the same `Meter` to create an instrument with the +name `RequestCount`, in both cases an instrument with the name `requestCount` +needs to be returned to the user and a log message needs to be emitted for the +second request. ### Instrument name From f05f132cde58fc21eff693e980f09d6f6a2d6c71 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 26 Jul 2023 12:31:29 -0700 Subject: [PATCH 5/7] Revert instrument instance section --- specification/metrics/sdk.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 3fb29596a71..59da5a29222 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -792,12 +792,13 @@ the user on how to resolve the conflict, if possible. data by reporting both `Metric` objects and emit a generic warning describing the duplicate instrument registration. -Outside of the following [sub-section](#name-conflict), it is unspecified -whether or under which conditions the same or different Instrument instance -will be returned as a result of duplicate instrument registration. The term -_identical_ applied to Instruments describes instances where all [identifying -fields](./api.md#instrument) are equal. The term _distinct_ applied to -Instruments describes instances where at least one field value is different. +It is unspecified whether or under which conditions the same or +different Instrument instance will be returned as a result of +duplicate instrument registration. The term _identical_ applied to +Instruments describes instances where all [identifying +fields](./api.md#instrument) are equal. The term _distinct_ applied +to Instruments describes instances where at least one field value is +different. To accommodate [the recommendations from the data model](data-model.md#opentelemetry-protocol-data-model-producer-recommendations), From 190269a9e697d6ee91ee7647807afc008b8d625e Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Thu, 27 Jul 2023 07:22:57 -0700 Subject: [PATCH 6/7] Update CHANGELOG.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d56098a203..2a8960e2bdf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ release. ### Metrics - Specify how to handle instrument name conflicts. - ([#TBD](/~https://github.com/open-telemetry/opentelemetry-specification/pull/TBD)) + ([#3626](/~https://github.com/open-telemetry/opentelemetry-specification/pull/3626)) - Add experimental metric attributes advice API. ([#3546](/~https://github.com/open-telemetry/opentelemetry-specification/pull/3546)) From 5948410b8def125a19cebac9d45a642ef829bf9d Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Tue, 1 Aug 2023 09:34:31 -0700 Subject: [PATCH 7/7] Add entry in spec-compliance-matrix --- spec-compliance-matrix.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 3e78413dc95..0bd4ec11064 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -117,6 +117,7 @@ formats is required. Implementing more than one format is optional. | Instruments have an optional description. | | + | + | + | + | | | + | + | + | + | | | Instruments have an optional advice. | | | | | | | | | | | | | | A valid instrument MUST be created and warning SHOULD be emitted when multiple instruments are registered under the same `Meter` using the same `name`. | | | + | + | + | | | | | | | | +| Duplicate instrument registration name conflicts are resolved by using the first-seen for the stream name. | | | + | | | | | | | | | | | It is possible to register two instruments with same `name` under different `Meter`s. | | + | + | + | + | | | | + | + | + | | | Instrument names conform to the specified syntax. | | - | + | | + | | | | + | + | + | | | Instrument units conform to the specified syntax. | | - | + | | + | | | | + | + | + | |