stefanbirkner / jersey-micrometer

Automatic Micrometer/Jersey integration

Jersey Micrometer

Jersey Micrometer uses Jersey 1, Micrometer and Guice to simplify gathering metrics for your JAX-RS resource methods.

Jersey Micrometer is published under the Apache Software License, Version 2.0. It requires at least Java 8.

Jersey Micrometer is a based on Marshall Pierce's jersey-metrics-filter library which uses Metrics instead of Micrometer.

Installation

Jersey Micrometer is available from Maven Central.

<dependency>
  <groupId>com.github.stefanbirkner</groupId>
  <artifactId>jersey-micrometer</artifactId>
  <version>1.0.3</version>
</dependency>

Usage

If you have a resource class like this:

@Path("whatever")
public class SomeResource {
    @GET
    public String get() {
        return "some data";
    }
}

then by using this library you will get a Timer metric generated for the get() method. The timers have three tags:

• method contains the HTTP method
• status contains the response's status code
• uri contains the request path

In this example a timer with the name http.server.requests is used. Its tag method has the value GET, the tag status has the value 200 and the tag uri has the value /whatever.

When the method throws an WebApplicationException then the status of the exception is used. If it throws another type of exception then the metric has the status "unknown".

Installation

The first step is to add this library's module and its prerequisites.

• ResourceMethodMicrometerModule is the module for this library.
• ResourceMethodWrappedDispatchModule is needed so that method invocation metrics can be captured without resorting to thread locals or other such unpleasantness.
• We also bind a MeterRegistry instance. The binding uses a binding annotation because it's impolite for a library to insist on an un-qualified binding of a common type like MeterRegistry. This MeterRegistry instance is what will be used to house all metrics generated by the library.

// in your Guice module
@Override
protected void configure() {
    install(new ResourceMethodMicrometerModule());

    // required for resource method metrics
    install(new ResourceMethodWrappedDispatchModule());

    MetricRegistry registry = new SimpleMeterRegistry();
    bind(MeterRegistry.class).annotatedWith(JerseyResourceMicrometer.class).toInstance(registry);

    ...

Configuration

By default metrics are collected for every resource method. You can change this behavior to not collecting metrics by default. Therefore you have to bind an instance of the Configuration class where metrics are disabled by default.

bind(Configuration.class)
    .toInstance(new Configuration().disabledByDefault());

You can override the default behavior by adding the annotation @ResourceMetrics to a class or method.

@Path("somewhere")
public class SomeResource {
    @GET
    @ResourceMetrics
    public String get() {
        return "ok";
    }
}

enables metrics collection for the method while

@Path("somewhere")
@ResourceMetrics
public class SomeResource {
    @GET
    public String get() {
        return "ok";
    }
}

enables metrics collection for all methods of the class. You can disable metric collection by setting the annotation's enabled flag to false

@ResourceMetrics(enabled = false)

If the annotation is present at a method and its class then the annotation at the method has precedence.

Development Guide

Jersey Micrometer is build with Maven. If you want to contribute code then

• Please write a test for your change.
• Ensure that you didn't break the build by running ./mvnw verify -Dgpg.skip.
• Fork the repo and create a pull request. (See Understanding the GitHub Flow)

The basic coding style is described in the EditorConfig file .editorconfig.

Jersey Micrometer supports Travis CI for continuous integration. Your pull request will be automatically build by Travis CI.

Release Guide

• Select a new version according to the Semantic Versioning 2.0.0 Standard.
• Set the new version in pom.xml and in the Installation section of this readme.
• Commit the modified pom.xml and README.md.
• Run ./mvnw clean deploy with JDK 8.
• Add a tag for the release: git tag jersey-micrometer-X.X.X