@Timed, @Metered, @ExceptionMetered Metrics Differences / Details

[Rob Williams]

Hi all,

I am currently running a Dropwizard HTTP service, tied to a Graphite backend for Metrics. I am using @Timed annotation on my resource, and see that Graphite receives timings that I assume are the response time of the resource. I have seen mentions of two other annotations : @Metered and @ExceptionMetered. However, I have not seen most people using these in code examples, and when trying to add them to my resource I receive a "IllegalArgumentException: x.y.z.Resource.method is already used for a different type of metric".

I am curious, what are the differences between these annotations? Are they meant to be used together, or only to pick one? I have scoured both the Metrics and Dropwizard documentation and have not found any specifics.

Is there any specific documentation on which metrics they capture? Additionally, it would be useful to know what other metrics Dropwizard makes available out of the box (i.e. if you do not use any annotations). I have found a few in Graphite related to different response status codes, as well as some more vaguely named "async-timeouts", "active-dispatches", etc. Any insight into how I can understand these metrics would be extremely helpful.

Thank you.
Rob

[Dimas Guardado]

Hi Rob,

There's a few questions here, so please let me know if I'm missing anything.

 * Core concepts: In Metrics, a Histogram is a statistical distribution of a stream of data, and a Meter measures *rates* of events. A Timer is a Histogram + a Meter. More specifically a Histogram of the timings of a particular call, and a Meter of the rate at which that call is invoked. Calls that are @Timed do not need to be @Metered because an invocation meter is already included in the timer. I'm not super familiar with the graphite reporter, but hopefully you can see the Histogram info in the form of Quantiles (median, 95, 98 %ile, etc) and the Meter info in the moving averages (5, 15 min average, etc). You would usually @Metered something when you're very interested in the call rate, but not especially interested in its timing. But you *probably* wouldn't use them together.

* IllegalArgumentException - The error you're seeing is because, by default, @Timed and @Metered annotations will try register their metrics with the same name in the Registry. Metrics doesn't like this and will let you know. :) If you really *want* to use both (though I can't imagine why) you can specify custom names in the parameters for the annotations.

* @ExceptionMetered - As the name indicates, this will create a Meter of the unhandled Exceptions thrown out of this method. This is SUPER useful for tracking error rates, and can be used together with @Timed or @Metered annotations, or entirely by itself. It will create a name in the registry that will not collide with @Timed or @Metered metrics.

* Documentation - Documentation for the behavior of Metrics, Reporters, and many of the instrumentable components can be found in the Metrics user manual[1]. Many (if not all) of these instrumented components are used in Dropwizard. A breakdown of the Metrics themselves can be found in the Getting Started Guide[2].

As a future note, this question may have been better fielded in the metrics-user mailing list[3] and I'll refer you there if you have further questions about Metrics internals.

Please let me know if I missed anything or can clarify anything further.

Best,
Dimas

[1] https://dropwizard.github.io/metrics/3.1.0/manual/
[2] https://dropwizard.github.io/metrics/3.1.0/getting-started/
[3] https://groups.google.com/forum/#!forum/metrics-user