Clarify whether multiple callbacks are allowed for async instruments

[jack-berg]

What are you trying to achieve?

Clarify behavior of metrics API / SDK when multiple callbacks are registered to the same instrument. The api spec says:

Meter implementations MUST return an error when multiple Instruments are registered under the same Meter instance using the same name.

In java, we interpret that as meaning that you can't register conflicting instruments under the same name. However, if the instrument type, name, unit, and description match, we'll return the previously registered instrument.

For example, in the following snippet, no error is generated and counter1 and counter2 are the instrument.

    LongCounter counter1 = meter.counterBuilder("foo").build();
    LongCounter counter2 = meter.counterBuilder("foo").build();

This makes sense for synchronous instruments, but its not clear what to do in the async case. Currently, if multiple callbacks are registered for the same instrument, we silently ignore registrations after the first. This isn't great, and minimally we should log an error when subsequent callbacks are registered. However, there's also an argument to made that registering multiple callbacks should be allowed and should result in each being invoked.

This has been raised in Issue #4051 and we believe it needs raising in the spec for resolution.

In particular, we want to make sure that our plans to publish a stable version of the metrics API would not be impacted by the spec resolution of this issue.

Additional context.

Issue #4005 aims to log a warning when multiple callbacks are registered, and is implemented in Issue #4020.

[reyang]

Meter implementations MUST return an error when multiple Instruments are registered under the same Meter instance using the same name.

It seems this statement in the spec is clear, do we expect to "have more clarification" or "change the behavior"?

In java, we interpret that as meaning that you can't register conflicting instruments under the same name. However, if the instrument type, name, unit, and description match, we'll return the previously registered instrument.

I can see problems, the API spec allows optional parameters to be added in the future, which might break Java's implementation.

[jsuereth]

Meter implementations MUST return an error when multiple Instruments are registered under the same Meter instance using the same name.

It seems this statement in the spec is clear, do we expect to "have more clarification" or "change the behavior"?

I actually was the one who misinterpreted this (when first approving the PR and then when implementing). I think this is far too restrictive as written and really diverges from getTracer and getLogger conventions. I suspect this limitation will dramatically hurt instrumentation in open-world systems. I'd argue we should consider this a major bug/user friction issue we should address.

In java, we interpret that as meaning that you can't register conflicting instruments under the same name. However, if the instrument type, name, unit, and description match, we'll return the previously registered instrument.

I can see problems, the API spec allows optional parameters to be added in the future, which might break Java's implementation.

We need to define instrument identity. If we add new parameters that alter instrument identity, we're likely causing user-friction/breakages. I'd like to understand what sorts of parameters we'd add (that alter metric identity) that are non-breaking for other implementations.

[jack-berg]

Resolved in #2317.