Verify compliant metric API specification implementation: Instrument Asynchronous Counter

[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]

#3453

[MrAlias]

#3454

[MrAlias]

There MUST NOT be any API for creating an Asynchronous Counter other than with a Meter.

With #3454 now complete, our implementation is compliant.

[MrAlias]

This MAY be called CreateObservableCounter. If strong type is desired, OpenTelemetry API authors MAY decide the language idiomatic name(s), for example CreateUInt64ObservableCounter, CreateDoubleObservableCounter, CreateObservableCounter<UInt64>, CreateObservableCounter<double>.

We do not follow this optional criteria. We instead follow more common Go method naming and use Int64ObservableCounter and Float64ObservableCounter.

[MrAlias]

It is highly recommended that implementations use the name ObservableCounter (or any language idiomatic variation, e.g. observable_counter) unless there is a strong reason not to do so.

I'm going to assume the authors intended "recommended" to be the normative key word "RECOMMENDED".

We do not follow this recommendation. #3453 is tracking this issue.

[MrAlias]

OpenTelemetry API authors MAY decide what is the idiomatic approach. Here are some examples:

• Return a list (or tuple, generator, enumerator, etc.) of Measurements.
• Use an observable result argument to allow individual Measurements to be reported.

This looks to be an inappropriate use of the normative key word "MAY" here. For what it's worth, we do choose the option to design an idiomatic approach.

The single callback design is being added in #3507, and the multi-callback is being defined in #3564.

[MrAlias]

User code is recommended not to provide more than one Measurement with the same attributes in a single callback. If it happens, OpenTelemetry SDK authors MAY decide how to handle it in the SDK. For example, during the callback invocation if two measurements value=1, attributes={pid:4, bitness:64} and value=2, attributes={pid:4, bitness:64} are reported, OpenTelemetry SDK authors MAY decide to simply let them pass through (so the downstream consumer can handle duplication), drop the entire data, pick the last one, or something else.

This is all not relevant to the API.

[MrAlias]

The API MUST treat observations from a single callback as logically taking place at a single instant, such that when recorded, observations from a single callback MUST be reported with identical timestamps.

The API does not handle collection cycles or the timestamping of observations, that is done by implementations receiving data from the API. Our implementation seems to comply with this as it treats observations agnostically regarding the time an observation occurs.

[MrAlias]

The API SHOULD provide some way to pass state to the callback. OpenTelemetry API authors MAY decide what is the idiomatic approach (e.g. it could be an additional parameter to the callback function, or captured by the lambda closure, or something else).

Similar to discussed here we pass a context.Context.

[MrAlias]

Remaining:

• Asynchronous Instrument API does not follow OTel Specification recommendation on naming #3453

[MrAlias]

Every normative clause from the Asynchronous Counter section of the v1.16.0 specification has been identified and our API has been validated that it complies. Closing.