39. Metrics

Spring Boot Actuator includes a metrics service with ‘gauge’ and ‘counter’ support. A ‘gauge’ records a single value; and a ‘counter’ records a delta (an increment or decrement). Metrics for all HTTP requests are automatically recorded, so if you hit the metrics endpoint should should see a response similar to this:

{
    "counter.status.200.root": 20,
    "counter.status.200.metrics": 3,
    "counter.status.200.star-star": 5,
    "counter.status.401.root": 4,
    "gauge.response.star-star": 6,
    "gauge.response.root": 2,
    "gauge.response.metrics": 3,
    "classes": 5808,
    "classes.loaded": 5808,
    "classes.unloaded": 0,
    "heap": 3728384,
    "heap.committed": 986624,
    "heap.init": 262144,
    "heap.used": 52765,
    "mem": 986624,
    "mem.free": 933858,
    "processors": 8,
    "threads": 15,
    "threads.daemon": 11,
    "threads.peak": 15,
    "uptime": 494836
}

Here we can see basic memory, heap, class loading, processor and thread pool information along with some HTTP metrics. In this instance the root (‘/’) and /metrics URLs have returned HTTP 200 responses 20 and 3 times respectively. It also appears that the root URL returned HTTP 401 (unauthorized) 4 times. The double asterix (star-star) comes from a request matched by Spring MVC as /** (normally a static resource).

The gauge shows the last response time for a request. So the last request to root took 2ms to respond and the last to /metrics took 3ms.

[Note]Note

In this example we are actually accessing the endpoint over HTTP using the /metrics URL, this explains why metrics appears in the response.

39.1 Recording your own metrics

To record your own metrics inject a CounterService and/or GaugeService into your bean. The CounterService exposes increment, decrement and reset methods; the GaugeService provides a submit method.

Here is a simple example that counts the number of times that a method is invoked:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.actuate.metrics.CounterService;
import org.springframework.stereotype.Service;

@Service
public class MyService {

    private final CounterService counterService;

    @Autowired
    public MyService(CounterService counterService) {
        this.counterService = counterService;
    }

    public void exampleMethod() {
        this.counterService.increment("services.system.myservice.invoked");
    }

}
[Tip]Tip

You can use any string as a metric name but you should follow guidelines of your chosen store/graphing technology. Some good guidelines for Graphite are available on Matt Aimonetti’s Blog.

39.2 Metric repositories

Metric service implementations are usually bound to a MetricRepository. A MetricRepository is responsible for storing and retrieving metric information. Spring Boot provides an InMemoryMetricRepository and a RedisMetricRepository out of the box (the in-memory repository is the default) but you can also write your own. The MetricRepository interface is actually composed of higher level MetricReader and MetricWriter interfaces. For full details refer to the Javadoc.

There’s nothing to stop you hooking a MetricRepository with back-end storage directly into your app, but we recommend using the default InMemoryMetricRepository (possibly with a custom Map instance if you are worried about heap usage) and populating a back-end repository through a scheduled export job. In that way you get some buffering in memory of the metric values and you can reduce the network chatter by exporting less frequently or in batches. Spring Boot provides an Exporter interface and a few basic implementations for you to get started with that.

39.3 Coda Hale Metrics

User of the Coda Hale ‘Metrics’ library will automatically find that Spring Boot metrics are published to com.codahale.metrics.MetricRegistry. A default com.codahale.metrics.MetricRegistry Spring bean will be created when you declare a dependency to the com.codahale.metrics:metrics-core library; you can also register you own @Bean instance if you need customizations.

Users can create Coda Hale metrics by prefixing their metric names with the appropriate type (e.g. histogram.*, meter.*).

39.4 Message channel integration

If the ‘Spring Messaging’ jar is on your classpath a MessageChannel called metricsChannel is automatically created (unless one already exists). All metric update events are additionally published as ‘messages’ on that channel. Additional analysis or actions can be taken by clients subscribing to that channel.