Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specify how to handle instrument name conflicts #3606

Closed
wants to merge 6 commits into from
Closed
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
66 changes: 42 additions & 24 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
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
MrAlias marked this conversation as resolved.
Show resolved Hide resolved

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
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
`name`, a duplicate instrument registration will occur when a user passes
multiple casings of the same `name`.
MrAlias marked this conversation as resolved.
Show resolved Hide resolved

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
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
better handled "downstream" in an exporter or collection system that will have
better context for how to handle the conflict.
MrAlias marked this conversation as resolved.
Show resolved Hide resolved

### Instrument name

When a Meter creates an instrument, it SHOULD validate the instrument name
Expand Down
Loading