Specify how to handle instrument name conflict (open-telemetry#3626)

- Refactor the "Duplicate instrument registration" section - Clarify how to handle when instrument names differ by only their casing: 1. Return the first-seen instrument name for all conflicting instrument names 2. Log a warning Resolves open-telemetry#3539
carlosalberto · Aug 9, 2023 · 0a8b685 · 0a8b685
1 parent f11712b
commit 0a8b685
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 17 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,8 @@ release.
 
 ### Metrics
 
+- Specify how to handle instrument name conflicts.
+  ([#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))
 - Revise the exemplar default reservoirs.

diff --git 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.                                                                                                                      |          | -  | +    |     | +      |      |        |     | +    | +   | +    |       |

diff --git 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)
@@ -766,13 +767,32 @@ 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
+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).
+
+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).
 
+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. 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.
+
 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
@@ -786,19 +806,20 @@ 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.
 
-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.
+#### Name conflict
 
-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.
-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.
+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
+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