Metric API specification overreaches into specifying implementation

[MrAlias]

The metric API specification contains many normative criteria for how the API should be implemented. It is not limited to the normative criteria that define the OpenTelemetry metric API. For example:

• Thus, implementations of MeterProvider SHOULD allow creating an arbitrary number of MeterProvider instances.

• This name SHOULD uniquely identify the instrumentation scope [...]

• In case an invalid name (null or empty string) is specified, a working Meter implementation MUST be returned as a fallback rather than returning null or throwing an exception, its nameproperty SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged.

• Implementations MUST NOT require users to repeatedly obtain a Meter with the same identity to pick up configuration changes.

• When more than one Instrument of the same name is created for identical Meters [...] the implementation MUST create a valid Instrument in every case.

• When 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).

• Distinct Meters MUST be treated as separate namespaces for the purposes of detecting duplicate instrument registration conflicts

Having normative statements made in the API documentation about the implementation poses two issues:

1. It introduces confusion about implementation requirements and recommendations.
   • OTel authors looking for requirements and recommendations of the SDK they are building need to look in the API specification as well as the SDK. This is not intuitive and likely missed by most.
   • Many (though, not all) of these statements are duplicated in the SDK specification. This means authors need to resolve any normative criteria overlap with the SDK. This also introduces bug opportunities when one changes but not the other.
2. It does not actually apply to all implementations.
   • Many of these statements do not or may not apply to no-op implementations. Having these statements in the API specification means that any any no-op implementation offered by an OTel language that does not meet all these criteria is non-compliant.
   • This gives the false sense that 3rd party implementations will follow this specification. This specification is defined for the OpenTelemetry project. Implementations outside the domain of OpenTelemetry are, by definition, outside the scope of this specification.

A thing to note here is that it is important to communicate to the users of the actual OTel APIs written in a programming language what they should expect to happen to the data provided. I expect this was a motivation of the original authors in including normative statements about API implementations here. However, the approach to achieve this aim needs to be carefully considered.

The specification is not the place users of the OTel APIs go to understand this data exchange. They refer to the documentations provided by the language project the API is built in. The intended reader of the specification is the developer of the language project, not the user of the OTel API. Understanding this means that adding normative implementation statements to the API does not achieve the goal of informing the end user. If we want to achieve this, the API specification needs to include normative criteria to ensure the built APIs are documented with expository statements about how the API should be called.

Proposal

1. Remove normative criteria about API implementation from the metric API specification.
   • Ensure any removal from the metric API specification has an equivalent criteria in the metric SDK (this assumes the original authors intent was to specify the SDK).
     • If it does not, add it to the SDK.
     • If it does, make sure the criteria are equivalent.
   • Replace any normative criteria about API implementation that was intended to describe to the user of the API how the data they passed would be validated or used with recommendations to language implementation to include in their documentation of the API expository statements that communicate this message.
2. Specify the no-op implementation of the API explicitly in its own specification document or as a section of the SDK document.

[MrAlias]

It was pointed out in the Go SIG meeting today that by the specification structured this way the no-op Meter will log warnings for duplicate instruments. This is not a good user experience. A user will likely use a no-op setup to disable all output from OTel and expect it to perform no operations. However, by needing to track duplicate instruments the Meter will indeed need to perform comparison operations and maintain state.

cc @Aneurysm9

[tsloughter]

facepalm this made me realize in Erlang we have log messages in the API for things like Counter add being passed something that isn't a non-negative number. Surely don't want that if no Meter is setup.

[jmacd]

I fully support this proposal, both points (1) and (2).