Metrics Annotations

[fstab]

Frameworks like Spring Boot, MicroProfile, and Dropwizard offer annotations like @Timed or @Counted for creating metrics from method calls.

The benefit is that developers can provide metrics for their business logic while still separating business code from metrics tracking.

@Timed
@Counted
public void processPayment() {
    // business code here
}

The OpenTelemetry Java auto instrumentation supports the @WithSpan annotation for tracing, but has nothing equivalent for metrics yet.

Brainstorming of a few ideas:

• For @Timed the type of histogram should be configurable, like @Timed(histogramType = EXPONENTIAL). Other histogram types would be explicit buckets and default buckets.
• Explicit buckets should be configurable: @Timed(buckets = { 0.001, 0.002, 0.003, 0.004 })
• For exponential histograms the resolution should be configurable.
• Static attributes should be configurable: @Counted(attributes = { "key", "value" })
• Dynamic attributes should be configurable similar to OpenTelemetry's @SpanAttribute.
• Dynamic attributes based on the return value and on an exception thrown would be great.

Moreover, it would be awesome to integrate this with @WithSpan so that develpers can say "I want to time this method AND have a Span". However, it should also be possible to use tracing without metrics, because histograms may introduce a lot of cardinality, and users might just want to create a Span without creating a histogram.

What do you think, is it worthwhile to put some more thoughts into this?

[jkwatson]

I think things that are a strict SDK responsibility (bucket definitions for example) should not end up being referenced in an annotation, since the annotations should be a pure API artifact.

Aside from that detail, I think having something like this would be a great idea.

[fstab]

Thanks for the quick response.

If a user wants to time something that takes microseconds they certainly want to use different buckets than if they time something that takes milliseconds or even seconds.

How would a user do that? Are there alternatives to configuring buckets in the annotation?

[jkwatson]

At the moment, all configuration of how histograms work (and metrics aggregations in general) is the responsibility of the application operator via SDK configuration, and is not a concern assigned to instrumentation authors. In the future, we may have what we've been calling a "hint" API that would allow instrumentation call sites to inform the SDK of what they would prefer, but that is not currently specified.

[fstab]

Thanks a lot for the explanation, this makes sense. In that case the annotations would be quite simple, as they only provide configuration options for the metric name and attributes.

I could open a PR to add them to extensions/annotations/ so that we can continue the discussion based on concrete examples. What do you think?

[jkwatson]

Thanks a lot for the explanation, this makes sense. In that case the annotations would be quite simple, as they only provide configuration options for the metric name and attributes.

I could open a PR to add them to extensions/annotations/ so that we can continue the discussion based on concrete examples. What do you think?

That would be fine. Since these annotations are generally implemented by the instrumentation folks, I'd love some feedback on this proposal from @trask @mateuszrzeszutek @anuraaga and others.

[trask]

I support! please tag @open-telemetry/java-instrumentation-approvers on your PR and we can discuss specifics there

[fstab]

Opened PR open-telemetry/opentelemetry-java#4260.

[trask]

@zeitlinger this could be a good use case for a convenience API until we implement an annotation-driven approach

linking to open-telemetry/opentelemetry-java-contrib#759