diff --git a/specification/metrics/api.md b/specification/metrics/api.md index c5d75d81660..7267e279cfc 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: @@ -264,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 f85f92b061b..6825a5aa0ca 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -952,3 +952,29 @@ 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. + +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. This is also covered in the +[supplemental guidelines for handling asynchronous instrument +views](#asynchronous-example-attribute-removal-in-a-view).