diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c52d225d68..c38ae70674d 100644 --- 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 index 2e3186f2a30..0dfc50555e5 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. | | - | + | | + | | | | + | + | + | | diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index e09f18ff222..68d6a60dfe6 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) @@ -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