Helidon gives you flexibility in how you make metrics available to your service. This document explains your options.

You add metrics to your service by writing code which explicitly invokes the metrics API to register metrics, retrieve previously-registered metrics, and update metric values.

Later sections of this document describe how to do this.

Helidon distinguishes among three general types, or scopes, of metrics, as described in the MP metrics specification.

When you add metrics annotations to your service code, Helidon registers the resulting metrics as type application.

A metric registry collects registered metrics of a given type. Helidon supports three registries, one for each of the three metrics types.

When you add code to your service to create a metric programmatically, the code first locates the appropriate registry and then registers the metric with that registry.

When you add the metrics dependency to your project, Helidon automatically provides a built-in REST endpoint /metrics which responds with a report of the registered metrics and their values.

Clients can request a particular output format.

Clients can also limit the report by appending the metric type to the path:

• /metrics/base

• /metrics/vendor

• /metrics/application

Further, clients can narrow down to a specific metric name by adding the name as a subpath such as /metrics/application/myCount.

curl -s -H 'Accept: text/plain' -X GET http://localhost:8080/metrics/

# TYPE base:classloader_total_loaded_class_count counter
# HELP base:classloader_total_loaded_class_count Displays the total number of classes that have been loaded since the Java virtual machine has started execution.
base:classloader_total_loaded_class_count 3157

curl -s -H 'Accept: application/json' -X GET http://localhost:8080/metrics/

{
   "base" : {
      "memory.maxHeap" : 3817865216,
      "memory.committedHeap" : 335544320,
    }
}

In addition to your application metrics, the reports contain other metrics of interest such as system and VM information.

To enable the metrics REST endpoint:

1. Create an instance of MetricsSupport, either directly as shown below or using its Builder.
2. Include the MetricsSupport instance in your application’s routing.

import io.helidon.metrics.serviceapi.MetricsSupport;

Routing.builder()
        .register(MetricsSupport.create())
        .register("/myapp", new MyService())
        .build();

The Helidon Metrics API is aligned with the MicroProfile Metrics API. That API defines the classes and interfaces for metric types, metric registries, and other related items. Helidon Metrics reuses that API for classes and interfaces (but not for annotations which Helidon SE does not support).

The following table summarizes the metric types.

Each metric type has its own set of methods for updating and retrieving the metric’s value.

To register or look up metrics programmatically, your service code uses one of the three MetricRegistry instances (base, vendor, and application) which Helidon furnishes automatically.

To get a MetricRegistry reference, first get a Helidon RegistryFactory. Then invoke getRegistry on the RegistryFactory instance.

The MetricRegistry allows your code to register new metrics, look up previously-registered metrics, and remove metrics.

The following example illustrates registering and updating a new Counter in application code.

import io.helidon.metrics.api.RegistryFactory;
import org.eclipse.microprofile.metrics.Counter;
import org.eclipse.microprofile.metrics.MetricRegistry;
//...

public class MyService implements Service {

    private final MetricRegistry registry = RegistryFactory.getInstance()
        .getRegistry(MetricRegistry.Type.APPLICATION); 
    private final Counter accessCtr = registry.counter("accessctr"); 

    @Override
    public void update(Routing.Rules rules) {
        rules
             .any(this::countAccess)
             .get("/", this::myGet);
    }

    private void countAccess(ServerRequest request, ServerResponse response) {
            accessCtr.inc(); 
            request.next();
    }
}

• Get the application metric registry.
• Create a counter in that registry.
• Increment the counter for every request.

• Disable Metrics Subsystem

• Disable Selected Metrics

• Collecting Basic and Extended Key Performance Indicator (KPI) Metrics

Metrics configuration is quite extensive and powerful and, therefore, a bit complicated. The rest of this section illustrates some of the most common scenarios.

Disable Metrics Subsystem

metrics:
  enabled: false

Disable Selected Metrics

metrics:
  registries:
    - type: application
      filter:
        exclude: "myapp\.supplier\..*"
        include: "myapp\.supplier\.updates"

Collecting Basic and Extended Key Performance Indicator (KPI) Metrics

metrics:
  key-performance-indicators:
    extended: true
    long-running:
      threshold-ms: 2000

• Maven Coordinates

• Usage

• API

Helidon provides optional support for the Prometheus metrics API.

To use it, your service registers Prometheus support with your routing set-up. You can customize its configuration. For information about using Prometheus, see the Prometheus documentation: https://prometheus.io/docs/introduction/overview/.

Maven Coordinates

    <dependency>
        <groupId>io.helidon.metrics</groupId>
        <artifactId>helidon-metrics-prometheus</artifactId>
    </dependency>

Usage

API

import io.helidon.metrics.prometheus.PrometheusSupport;

Routing.builder()
                .register(PrometheusSupport.create())
                .register("/myapp", new MyService())
                .build();