34. 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.401.root": 4,
    "gauge.response.root": 2,
    "gauge.response.metrics": 3,
    "mem": 466944,
    "mem.free": 410117,
    "processors": 8
}

Here we can see basic memory and processor 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 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.

34.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.

34.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 InMemoryMessageRespository 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.

34.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.*).

34.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.