Tagging support for Dropwizard Jersey 2 Metrics

The Metrics project from Dropwizard does not natively support tags in version v4.x. However, tags can be encoded as part of the metric name. This library extends the Metrics Jersey 2 offering and provides support for it.

Documentation

The Metrics project comes with built-in support for collecting useful metrics for exposed JAX-RS resource methods. In certain use cases it might be helpful or even necessary to expose more granular default metrics, for example by adding a tenant dimension. This can be achieved by implementing custom metrics, but comes with quite some boiler plate code.

This library tries to combine the power of Dropwizard`s default Metrics annotations with a flexible approach to add tags dynamically that are automatically evaluated by the Jersey server framework.

Dependencies

The implementation is based on io.dropwizard.metrics:metrics-jersey2:4.1.12.1. It is compatible with Metrics since version v4.0.0, bundled with Dropwizard since version v1.3.0.

Getting started

The artifacts including source and binaries are available on the central Maven repositories.

For maven:

<dependency>
  <groupId>de.peetzen.dropwizard.metrics</groupId>
  <artifactId>metrics-tagging-jersey2</artifactId>
  <version>1.0.2</version>
</dependency>

For gradle:

implementation group: 'de.peetzen.dropwizard.metrics', name: 'metrics-tagging-jersey2', version: '1.0.2'

Usage

The MetricDynamicTaggingFeature needs to be registered with the Jersey environment and afterwards tags can be added to the default metrics using static MetricTaggingContext#put(..) from within the resource methods.

To expose metrics, the resource methods need to be annotated with at least one of the Metrics annotations

• @Metered
• @Timed
• @ExceptionMetered
• @ResponseMetered

The collected metrics of a @Timed annotated resource method can be controlled using the MetricDynamicTaggingFeature constructors, analogue to the built-in MetricsFeature.

To differentiate between the default metrics and the ones with tags, a suffix is added to the metric names. The default is tagged and can be controlled using MetricDynamicTaggingFeature constructors.

If no tags are present, nothing will be captured. In this case the MetricFeature metrics are equivalent.

Dropwizard Example

Register the Jersey feature MetricDynamicTaggingFeature within your Dropwizard application.

public class MyApplication extends Application<MyConfiguration> {

    @Override
    public void run(MyConfiguration configuration, Environment environment) {
        doOtherInitialisations();
        
        // register feature to support dynamic tags using the dropwizard default annotation names
        environment.jersey().register(new MetricsDynamicTaggingFeature(environment.metrics()));
    }
}

Add dynamic tags within resource implementation using MetricTaggingContext#put(..).

@Path("/")
@Produces(MediaType.APPLICATION_JSON)
class MyResource {

    @GET
    @Timed
    @ExceptionMetered
    @ResponseMetered
    Response getStatus() {
    
        // add dynamic "tenant" tag that will be part of tagged resource metrics
        MetricTaggingContext.put("tenant", getTenant());
        
        doSomething();
        
        return Response.ok("{\"status\":\"active\"}").build();
    }
}

Exposed Metrics

Classic metrics:

• my.package.MyResource.getStatus
• my.package.MyResource.getStatus.request.filtering
• my.package.MyResource.getStatus.response.filtering
• my.package.MyResource.getStatus.total
• my.package.MyResource.getStatus.Xxx-responses (1xx, .. 5xx)
• my.package.MyResource.getStatus.exceptions

Additional tagged metrics (using default MetricsDynamicTaggingFeature configuration):

• my.package.MyResource.getStatus.tagged[tenant:tenant_id]
• my.package.MyResource.getStatus.tagged.Xxx-responses[tenant:tenant_id] (1xx, .. 5xx)
• my.package.MyResource.getStatus.tagged.exceptions[tenant:tenant_id]