MP metrics spec and JavaDoc could use some clarification on reusability

[Tim Quinn]

The spec discussion of metric reusability gives an example about reuse via annotations, and it also discusses how metrics created via annotations are not by default reusable, while those created via the MetricRegistry API are.

But nowhere in the MetricRegistry JavaDoc is reusability mentioned, so it's not at all clear which of those methods -- if any -- would enforce reusability.

The JavaDoc for the type-based MetricRegisty methods -- concurrentGauge, counter, histogram, meter, timer -- describe "lookup-first-then-register-if-absent" semantics. There's no hint of using the reusability setting if the metric already exists.

For the register methods, the doc states that it's an error for the caller to specify a metric that has already been registered. There's no mention of reusability there either.

So, is it true that none of the MetricRegistry methods themselves should enforce reusability? Or, is it really true that reusability is intended to apply only to metrics registered via annotation?

It'd be great to hear on this thread what the intent is, and to see the spec and/or JavaDoc clarified in a future release.

- Tim

[Jan Martiska]

Hi Tim,
thanks for noticing and pointing out this insufficiency, you are right that this would deserve some more explanation. I filed an issue [1] and we will get it resolved as soon as we get round to it.

Generally, reusability is intended to apply to annotated metrics only (that's why programmatically registered methods are considered reusable and making them explicitly non-reusable basically makes no sense). Reusability allows you to reference the same metric instance from multiple annotated methods. The concept was introduced to prevent the developer from copy-paste errors when they, for example, copy a code block including metric annotations into a different class, and then at runtime they get surprised that instead of getting multiple metrics, they get just one metric that is reused at multiple places. Now they have to explicitly enable reusability, thus acknowledging that they know what the effect will be.

For the MetricRegistry.register() method, it is of course an error to attempt to re-register a metric - this has nothing to do with reusability though. Reusability is the ability to reference the same metric from multiple annotated methods, it has nothing to do with re-registering the same metric multiple times. We will look into how we can clarify this better.

Thanks

Jan

[1] https://github.com/eclipse/microprofile-metrics/issues/453

[Tim Quinn]

Hi, Jan. I appreciate the clarification.

The spec does a good job, as you did, of explaining the rationale regarding reusability with respect to annotations. 

Given your explanation, the fact that reusability is recorded in the metadata -- which implies that it applies to all metrics, not just annotation sites -- contributes to the confusion. It might have been clearer if reusable had been defined on the annotations only and not also in the metadata, but we are where we are! 

A brief clarification in the spec and/or the JavaDoc for the reusability-related methods on MetadataBuilder or Metadata will definitely help.

Thanks.

- Tim