Quick Start

Get the artifacts

Artifacts are released in Maven Central.

Maven:

<dependency>
  <groupId>com.palominolabs.metrics</groupId>
  <artifactId>metrics-guice</artifactId>
  <version>[the latest version]</version>
</dependency>

Gradle:

compile 'com.palominolabs.metrics:metrics-guice:[the latest version]'

Install the Guice module

// somewhere in your Guice module setup
install(MetricsInstrumentationModule.builder().withMetricRegistry(yourFavoriteMetricRegistry).build());

Use it

The MetricsInstrumentationModule you installed above will create and appropriately invoke a Timer for @Timed methods, a Meter for @Metered methods, a Counter for @Counted methods, and a Gauge for @Gauge methods. @ExceptionMetered is also supported; this creates a Meter that measures how often a method throws exceptions.

The annotations have some configuration options available for metric name, etc. You can also provide a custom MetricNamer implementation if the default name scheme does not work for you.

Customizing annotation lookup

By default MetricsInstrumentationModule will provide metrics only for annotated methods. You can also look for annotations on the enclosing classes, or both, or provide your own custom logic. To change annotation resolution, provide an AnnotationResolver when building the MetricsInstrumentationModule. MethodAnnotationResolver is the default implementation. ClassAnnotationResolver will look for annotations on the class instead of the method. You can invoke multiple resolvers in order with ListAnnotationResolver , so if you wanted to look in methods first and then the class, you could do that:

// somewhere in your Guice module setup
install(
    MetricsInstrumentationModule.builder()
        .withMetricRegistry(yourFavoriteMetricRegistry)
        .withAnnotationResolver(new ListAnnotationResolver(Lists.newArrayList(new ClassAnnotationResolver(), new MethodAnnotationResolver()))
        .build()
);

Metric namer

The default MetricNamer implementation probably does what you want out of the box, but you can also write and use your own.

Example

If you have a method like this:

class SuperCriticalFunctionality {
    public void doSomethingImportant() {
        // critical business logic
    }
}

and you want to use a Timer to measure duration, etc, you could always do it by hand:

public void doSomethingImportant() {
    // timer is some Timer instance
    Timer.Context context = timer.time();
    try {
        // critical business logic
    } finally {
        context.stop();
    }
}

However, if you're instantiating that class with Guice, you could just do this:

@Timed
public void doSomethingImportant() {
    // critical business logic
}

Limitations

Since this uses Guice AOP, instances must be created by Guice; see the Guice wiki. This means that using a Provider where you create the instance won't work, or binding a singleton to an instance, etc.

Guice AOP doesn't allow us to intercept method calls to annotated methods in supertypes, so @Counted, etc, will not have metrics generated for them if they are in supertypes of the injectable class. One small consolation is that @Gauge methods can be anywhere in the type hierarchy since they work differently from the other metrics (the generated Gauge object invokes the java.lang.reflect.Method directly, so we can call the supertype method unambiguously).

One common way users might hit this issue is if when trying to use @Counted, etc on a JAX-RS resource annotated with @Path, @GET, etc. This may pose problems for the JAX-RS implementation because the thing it has at runtime is now an auto-generated proxy class, not the "normal" class. A perfectly reasonable approach is instead to handle metrics generation for those classes via the hooks available in the JAX-RS implementation. For Jersey 2, might I suggest jersey2-metrics?