Metrics

SeedStack metrics add-on provides integration of CodaHale Metrics to monitor applicative metrics and health.

Dependency #

To add the Metrics add-on to your project, add the following dependency:

<dependency>
    <groupId>org.seedstack.addons.metrics</groupId>
    <artifactId>metrics</artifactId>
    <version>1.0.0</version>
</dependency>

dependencies {
    compile("org.seedstack.addons.metrics:metrics:1.0.0")
}

Configuration #

metrics:
  # Configuration of metrics publication
  servlets: 
    # If true, metrics HTTP publication is enabled (by default on the `path`)
    enabled: (Boolean)
    # Base path for HTTP publication (default is `/seed-metrics`)
    path: (String)
    # If true, a minimal HTML menu is published on base path (default is `false`)
    admin: (Boolean)
    # Application metrics
    metrics:
      # If true, application metrics are published (default is `true`)
      enabled: (Boolean)
      # Path suffix for application metrics (default is `/metrics`)
      path: (String)
    # Health checks
    health:
      # If true, health checks are published (default is `true`)
      enabled: (Boolean)
      # Path suffix for health checks (default is `/healthcheck`)
      path: (String)
    # Ping (availability status)
    ping:
      # If true, availability status is published (default is `true`)
      enabled: (Boolean)
      # Path suffix for availability status (default is `/ping`)
      path: (String)
    # Thread info
    threads:
      # If true, thread info is published (default is `false`)
      enabled: (Boolean)
      # Path suffix for thread info (default is `/threads`)
      path: (String)
    # CPU metrics (pprof format)
    cpu:
      # If true, CPU profiling stats are published (default is `false`)
      enabled: (Boolean)
      # Path suffix for CPU profiling stats (default is `/pprof`)
      path: (String)

mvn -q -Dargs="metrics" seedstack:config

HTTP publication #

In a Web application, the following information is published on HTTP by default:

• Application metrics as JSON, on <basePath>/metrics.
• Health check status as JSON, on <basePath>/healthcheck.
• Ping (availability status), always responding with 200 OK when the application is up and running, on <basePath>/ping.

The following information is not published by default for security reasons:

• CPU profiling info as GPerfTools format, on <basePath>/pprof.
• Thread dump as JSON, on <basePath>/threads.

Usage #

Metrics #

Five types of metrics can be measured:

• Gauge, which simply collects a value.
• Counter, which is an incrementing or decrementing value.
• Histogram, which measures the distribution of values in a stream of data.
• Meter, which measure the rate at which a set of events occur.
• Timer, which combines an histogram of an event duration and a meter of the rate of its occurrence.

@Gauge

To register a Gauge, use the <@Gauge annotation on any method:

public class SomeClass {
    @Gauge(name = "queueSize")
    public int getQueueSize() {
        return queue.size;
    }
}

@CachedGauge

You can also use its @CachedGauge counterpart which allows for a more efficient reporting of value which are expensive to calculate:

public class SomeClass {
    @CachedGauge(name = "queueSize", timeout = 30, timeoutUnit = TimeUnit.SECONDS)
    public int getQueueSize() {
        return queue.getSize();
    }
}

@Counted

The @Counted annotation will create a counter of the invocations of the method it is applied to:

public class SomeClass {
    @Counted(name = "fancyName")
    public String fancyName(String name) {
        return "Sir Captain " + name;
    }
}

Note that if the monotonic parameter is set to false, the counter is increment upon method entry and decremented upon method exit. If set to true, the counter only increments, effectively counting the number of method invocations.

@Metered

The @Metered annotation will create a meter which will measure the rate of invocation of the method it is applied to:

public class SomeClass {
    @Metered(name = "fancyName")
    public String fancyName(String name) {
        return "Sir Captain " + name;
    }
}

@ExceptionMetered

Its counter-part, the @ExceptionMetered annotation will create a meter which will measure the rate of exception throwing of the method it is applied to:

public class SomeClass {
    @ExceptionMetered
    public String fancyName(String name) {
        return "Sir Captain " + name;
    }
}

Generic @Metric

The more generic @Metric annotation permits two different uses. When applied on an empty Metric field, the corresponding metric will be created and injected:

public class SomeClass {
    @Metric
    private Meter meter;
}

When applied on a non-empty Metric field, the metric will be registered:

public class SomeClass {
    @Metric
    private Histogram uniformHistogram = new Histogram(new UniformReservoir());
}

In both cases, it is up to the client code to interact with the metric.

Registry

If you need more control over the metrics registration process, you can inject the MetricRegistry:

public class SomeClass {
    @Inject
    private MetricRegistry metricRegistry;
}

This also allows to interact programmatically with any registered metrics.

Health-checks #

An health check is a class that will check a specific state of the application and report it. To create an health check, you must extend the HealthCheck class and annotate it with the @HealthChecked annotation:

@HealthChecked
public class GoodHealthCheck extends HealthCheck {
    @Inject
    private MyService myService;
 
    @Override
    protected Result check() throws Exception {
        if (myService.isOk()) {
            return Result.healthy("I'm fine !");
        } else {
            return Result.unhealthy("Boo");
        }
    }
}