Verify compliant metric API specification implementation: Measurement

[MrAlias]

• Identify all the normative requirements, recommendations, and options the specification defines as comments to this issue
• Ensure the current metric API implementation is compliant with these normative requirements, recommendations, and options in those comments.

[MrAlias]

Measurement

A Measurement represents a data point reported via the metrics API to the SDK. Please refer to the Metrics Programming Model for the interaction between the API and SDK.

Measurements encapsulate:

• A value
• Attributes

There are no normative statements in this section. The only question that is raised is if this needs to be an explicit API or not?

The Histogram's Record operation is defined as receiving a Measurment.

• The amount of the Measurement, which MUST be a non-negative numeric value.

Our API accepts a float64 or int64 value directly and also passes attributes. I think this is an error in the specification as if one truly reported a Measurement, which is a value and attributes, but then also provided additional attributes, it would double provide attributes.

The other place a Measurement is mentioned is in the asynchronous instrument callback design. There it uses the term Measurement to represent the value/attributes pair.

Based on this analysis, I think the Histogram's Record operation in the specification needs to be updated, and after that this section is meant as a definition of the Measurement term only (not an implemented API).

[MrAlias]

Specification PR to correct histogram parameter language: open-telemetry/opentelemetry-specification#3083

[MrAlias]

Ah, it looks like this section also includes the "Multiple-instrument callbacks" as well. I'll follow up with evaluating that section next.

[MrAlias]

The Metrics API MAY support an interface allowing the use of multiple instruments from a single registered Callback.

We support this:

opentelemetry-go/metric/meter.go

Line 109 in 75a19d1

RegisterCallback(instruments []instrument.Asynchronous, f Callback) (Registration, error)

[MrAlias]

It is RECOMMENDED that the API authors use one of the following forms for the callback function:

• The list (or tuple, etc.) returned by the callback function contains (Instrument, Measurement) pairs.
• the Observable Result parameter receives an additional (Instrument, Measurement) pairs

We do not currently follow this recommendation. We should given there is no obvious reason to no as far as I can see.

The redesign of this method and its related callback is being tracked in #3519

[MrAlias]

Remaining:

• Open question: Fix Histogram parameter: use value term instead of Measurement opentelemetry-specification#3083
• Redesign of Asynchronous Instrument Registration API via the Meter #3519

[MrAlias]

Closed by #3519