Fork me on GitHub

Metrics Servlets

The metrics-servlets module provides a handful of useful servlets:

HealthCheckServlet

HealthCheckServlet responds to GET requests by running all the [health checks](#health-checks) and returning 501 Not Implemented if no health checks are registered, 200 OK if all pass, or 500 Internal Service Error if one or more fail. The results are returned as a human-readable text/plain entity.

HealthCheckServlet requires that the servlet context has a HealthCheckRegistry named com.codahale.metrics.servlets.HealthCheckServlet.registry. You can subclass MetricsServletContextListener, which will add a specific HealthCheckRegistry to the servlet context.

ThreadDumpServlet

ThreadDumpServlet responds to GET requests with a text/plain representation of all the live threads in the JVM, their states, their stack traces, and the state of any locks they may be waiting for.

MetricsServlet

MetricsServlet exposes the state of the metrics in a particular registry as a JSON object.

MetricsServlet requires that the servlet context has a MetricRegistry named com.codahale.metrics.servlets.MetricsServlet.registry. You can subclass MetricsServletContextListener, which will add a specific MetricRegistry to the servlet context.

MetricsServlet also takes an initialization parameter, show-jvm-metrics, which if "false" will disable the outputting of JVM-level information in the JSON object.

PingServlet

PingServlet responds to GET requests with a text/plain/200 OK response of pong. This is useful for determining liveness for load balancers, etc.

AdminServlet

AdminServlet aggregates HealthCheckServlet, ThreadDumpServlet, MetricsServlet, and PingServlet into a single, easy-to-use servlet which provides a set of URIs:

  • /: an HTML admin menu with links to the following:
    • /healthcheck: HealthCheckServlet
    • /metrics: MetricsServlet
    • /ping: PingServlet
    • /threads: ThreadDumpServlet

You will need to add your MetricRegistry and HealthCheckRegistry instances to the servlet context as attributes named com.codahale.metrics.servlets.MetricsServlet.registry and com.codahale.metrics.servlets.HealthCheckServlet.registry, respectively. You can do this using the Servlet API by extending MetricsServlet.ContextListener for MetricRegistry:

public class MyMetricsServletContextListener extends MetricsServlet.ContextListener {

    public static final MetricRegistry METRIC_REGISTRY = new MetricRegistry();

    @Override
    protected MetricRegistry getMetricRegistry() {
        return METRIC_REGISTRY;
    }

}

And by extending HealthCheckServlet.ContextListener for HealthCheckRegistry:

public class MyHealthCheckServletContextListener extends HealthCheckServlet.ContextListener {

    public static final HealthCheckRegistry HEALTH_CHECK_REGISTRY = new HealthCheckRegistry();

    @Override
    protected HealthCheckRegistry getHealthCheckRegistry() {
        return HEALTH_CHECK_REGISTRY;
    }

}

Then you will need to register servlet context listeners either in you web.xml or annotating the class with @WebListener if you are in servlet 3.0 environment. In web.xml:

<listener>
        <listener-class>com.example.MyMetricsServletContextListener</listener-class>
</listener>
<listener>
        <listener-class>com.example.MyHealthCheckServletContextListener</listener-class>
</listener>

You will also need to register AdminServlet in web.xml:

<servlet>
        <servlet-name>metrics</servlet-name>
        <servlet-class>com.codahale.metrics.servlets.AdminServlet</servlet-class>
</servlet>
<servlet-mapping>
        <servlet-name>metrics</servlet-name>
        <url-pattern>/metrics/*</url-pattern>
</servlet-mapping>