Instrument identity, registration conflicts, multi-callback registration, unregister support

specification/metrics/api.md

@@ -129,19 +129,24 @@ This API MUST accept the following parameters:
 * [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be
   recorded in the emitted telemetry.
 
-It is unspecified whether or under which conditions the same or different
-`Meter` instances are returned from this functions.
-
-Implementations MUST NOT require users to repeatedly obtain a `Meter` again with
-the same name+version+schema_url to pick up configuration changes. This can be
+Meters are identified by all of these fields.  When more than one
+Meter of the same `name`, `version`, and `schema_url` is created, it
+is unspecified whether or under which conditions the same or different
+`Meter` instances are returned.  Meter identity, and the terms
+_identical_ and _distinct_ applied to Meters in this specification
+describes Meter instances that have identical and/or distinct values
+for all three of their `name`, `version`, and `schema_url` attributes.
+
+Implementations MUST NOT require users to repeatedly obtain a `Meter` with
+the same identity to pick up configuration changes. This can be
 achieved either by allowing to work with an outdated configuration or by
 ensuring that new configuration applies also to previously returned `Meter`s.
 
 Note: This could, for example, be implemented by storing any mutable
 configuration in the `MeterProvider` and having `Meter` implementation objects
 have a reference to the `MeterProvider` from which they were obtained. If
 configuration must be stored per-meter (such as disabling a certain meter), the
-meter could, for example, do a look-up with its name+version+schema_url in a map
+meter could, for example, do a look-up with its identity in a map
 in the `MeterProvider`, or the `MeterProvider` could maintain a registry of all
 returned `Meter`s and actively update their configuration if it changes.
 
@@ -175,19 +180,50 @@ Instruments are used to report [Measurements](#measurement). Each Instrument
 will have the following information:
 
 * The `name` of the Instrument
-* The `kind` of the Instrument - whether it is a [Counter](#counter) or other
-  instruments, whether it is synchronous or asynchronous
+* The `kind` of the Instrument - whether it is a [Counter](#counter) or 
+  one of the other kinds, whether it is synchronous or asynchronous
 * An optional `unit` of measure
 * An optional `description`
 
-Instruments are associated with the Meter during creation, and are identified by
-the name:
+Instruments are associated with the Meter during creation. Instruments
+are identified by all of these fields.
+
+<a name="instrument-type-conflict-detection"></a>
+
+When more than one Instrument of the same `name` is created for
+identical Meters, denoted _duplicate instrument registration_, the
+implementation MUST return a valid Instrument in every case.
+
+It is unspecified whether or under which conditions the same or
+different Instrument instance will be returned as a result of
+duplicate instrument registration.  Instrument identity, and the terms
+_identical_ and _distinct_ applied to Instruments in this
+specification describes Instrument instances that have identical
+and/or distinct values for all four of their `name`, `kind`, `unit`,
+and `description` attributes.  Language-level features such the
+distinction between integer and floating point numbers SHOULD be
+considered as identifying, as well.
+
+The implementation MUST aggregate data from identical Instruments
+together in its export pipeline.
+
+When through duplicate registration more than one distinct Instrument
+is registered with the same `name` for identical Meters, the
+implementation SHOULD emit a warning to the user informing them of
+duplicate registration conflict(s).
+
+__Note the warning about duplicate instrumentation registration
+conflicts is meant to help avoid the semantic error state described in
+the [OpenTelemetry Metrics data
+model](datamodel.md#opentelemetry-data-model) when more than one kind
+of point is written for a given instrument `name` and Meter identity
+from the same process.
+
+<a name="instrument-namespace"></a>
 
-* 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.
+Distinct Meters MUST be treated as separate namespaces for the
+purposes of detecting [duplicate instrument registration
+conflicts](#instrument-type-conflict-detection).
 
 <a name="instrument-naming-rule"></a>
 
@@ -210,7 +246,7 @@ DIGIT = %x30-39 ; 0-9
 
 <a name="instrument-unit"></a>
 
-The `unit` is an optional string provided by the author of the instrument. It
+The `unit` is an optional string provided by the author of the Instrument. It
 SHOULD be treated as an opaque string from the API and SDK (e.g. the SDK is not
 expected to validate the unit of measurement, or perform the unit conversion).
 
@@ -239,7 +275,7 @@ 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.
 
-Instruments can be categorized based on whether they are synchronous or
+Instruments are categorized based on whether they are synchronous or
 asynchronous:
 
 <a name="synchronous-instrument"></a>
@@ -264,6 +300,25 @@ Please note that the term _synchronous_ and _asynchronous_ have nothing to do
 with the [asynchronous
 pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation).
 
+Considering duplicate registration of asynchronous instruments, the
+implementation MUST support multiple callbacks registered per
+identical instrument.
+
+The API MAY provide support for registration of a single callback
+having multiple asynchronous instruments, where idiomatic.  The
+implementation is REQUIRED to maintain a mapping from every regsitered
+callback to the associated instrument(s).
+
+The implementation MUST provide a way to unregister callbacks
+associated with asynchronous instruments.
+
+The implementation SHOULD reject observations that are made outside of
+a callback registered for the instrument.
+
+Callers SHOULD avoid making duplicate observations from asynchronous
+instrument callbacks, as the result of making duplicate observations
+is not specified.
+
 ### Counter
 
 `Counter` is a [synchronous Instrument](#synchronous-instrument) which supports
@@ -396,7 +451,10 @@ The API MUST accept the following parameters:
   rule](#instrument-unit).
 * An optional `description`, following the [instrument description
   rule](#instrument-description).
-* A `callback` function.
+
+The API MUST support an idiomatic way to associate one or more
+`callback` functions with each instrument, whether through the
+instrument constructor or a separate registration method.
 
 The `callback` function is responsible for reporting the
 [Measurement](#measurement)s. It will only be called when the Meter is being
@@ -613,7 +671,10 @@ The API MUST accept the following parameters:
   rule](#instrument-unit).
 * An optional `description`, following the [instrument description
   rule](#instrument-description).
-* A `callback` function.
+
+The API MUST support an idiomatic way to associate one or more
+`callback` functions with each instrument, whether through the
+instrument constructor or a separate registration method.
 
 The `callback` function is responsible for reporting the
 [Measurement](#measurement)s. It will only be called when the Meter is being
@@ -885,7 +946,10 @@ The API MUST accept the following parameters:
   rule](#instrument-unit).
 * An optional `description`, following the [instrument description
   rule](#instrument-description).
-* A `callback` function.
+
+The API MUST support an idiomatic way to associate one or more
+`callback` functions with each instrument, whether through the
+instrument constructor or a separate registration method.
 
 The `callback` function is responsible for reporting the
 [Measurement](#measurement)s. It will only be called when the Meter is being

specification/metrics/datamodel.md

@@ -263,18 +263,33 @@ can be converted directly into Timeseries, and share the same identity
 characteristics for a Timeseries. A metric stream is identified by:
 
 - The originating `Resource`
+- The metric's associated Meter details (`name`, `version`, and `schema_url`)
 - The metric stream's `name`.
 - The attached `Attribute`s
-- The metric stream's point kind.
+- The metric stream's point kind (`Sum`, `Gauge`, `Histogram` `ExponentialHistogram`)
 
 It is possible (and likely) that more than one metric stream is created per
 `Instrument` in the event model.
 
-__Note: The same `Resource`, `name` and `Attribute`s but differing point kind
-coming out of an OpenTelemetry SDK is considered an "error state" that SHOULD
-be handled by an SDK.__
-
-A metric stream can use one of these basic point kinds, all of
+Points with identical `name`, `Resource`, and Meter details but
+different point kind SHOULD be considered an "error state", due to
+semantic disagreement, whether or not they use distinct `Attribute`
+values.
+
+Consumers of OpenTelemetry metrics data streams MAY reject data
+containing the multiple point kinds for identical `name`, `Resource`,
+and Meter details, even though the [Single-Writer](#single-writer)
+rule is only broken when distinct `Attribute` values are involved.
+
+__Note: The OpenTelemetry SDK specification is written to explicitly
+permit duplicate instrumentation registration, which means the
+potential to produce the error state.  This is considered to be in the
+user's best interest.  Although the SDK has permission to pass-through
+duplicate instrument registration conflicts, consumers of
+OpenTelemetry metrics are given equal permission to reject the data
+because of semantic disagreement.
+
+A metric stream can use one of the basic point kinds, all of
 which satisfy the requirements above, meaning they define a decomposable
 aggregate function (also known as a “natural merge” function) for points of the
 same kind. <sup>[1](#otlpdatapointfn)</sup>
@@ -749,6 +764,7 @@ All metric data streams within OTLP MUST have one logical writer.  This means,
 conceptually, that any Timeseries created from the Protocol MUST have one
 originating source of truth.  In practical terms, this implies the following:
 
+@@@
 - All metric data streams produced by OTel SDKs MUST be globally uniquely
   produced and free from duplicates.   All metric data streams can be uniquely
   identified in some way.

specification/metrics/sdk.md

@@ -952,3 +952,26 @@ called concurrently.
 
 **MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called
 concurrently.
+
+## Data model requirements
+
+The [OpenTelemetry Metrics data
+model](datamodel.md#opentelemetry-protocol-data-model) has a [Single
+Writer](datamodel.md#single-writer) rule which the SDK is required to
+enforce, with one exception noted below.  This rule is the origin of
+the output-name uniqueness requirement for [Views](#view) and is the
+reason the API specifies that implementations MUST aggregate data for
+identical instruments in its pipeline.
+
+The implementation has permission to pass-through violations of the
+semantic "error state" described in the [OpenTelemetry Metrics data
+model](datamodel.md#opentelemetry-protocol-data-model).  This is to
+address the exceptional case of duplicate instrument registration
+conflicts, which are tolerated with warnings in the API.
+
+Duplicate instrument registration conflicts can produce this semantic
+error state, which may lead to violations of the single-writer rule.
+SDKs are permitted to allow these conflicts to take place to avoid
+user data loss.  Since the semantic conflict may not be resolvable
+downstream, Metrics data consumers MAY reject semantically conflicting
+data and SHOULD notify the user of the error, somehow, in such cases.