Helidon SE uses the term "metrics" to refer to the subsystem in Helidon which manages the registration of, updates to, and reporting of aggregate statistical measurements about the service. The term "meter" refers to an entity which collects these measurements, such as a counter or a timer.

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

Later sections of this document describe how to do this.

Helidon distinguishes among scopes, or types, of meters.

Helidon includes meters in the built-in scopes described below. Applications often register their own meters in the application scope but can create their own scopes and register meters within them.

When an application creates a new meter it can specify which scope the meter belongs to. If the application does not specify a scope for a new meter, the default scope is application.

Helidon stores all meters in a meter registry. Typically, applications use the global meter registry which is the registry where Helidon stores built-in meters. Application code refers to the global registry using Metrics.globalRegistry().

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

Clients can request a particular output format.

Clients can also limit the report by specifying the scope as a query parameter in the request URL:

• /observe/metrics?scope=base

• /observe/metrics?scope=vendor

• /observe/metrics?scope=application

Further, clients can narrow down to a specific metric name by adding the name as another query parameter, such as /observe/metrics?scope=application&name=myCount.

curl -s -H 'Accept: text/plain' -X GET http://localhost:8080/observe/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/observe/metrics

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

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

If you add the dependencies described above, your service automatically supports the metrics REST endpoint as long as the WebServer is configured to discover features automatically.

If you disable auto-discovery, you can add the metrics observer explicitly.

1. Create an instance of MetricsObserver, either directly as shown below or using its builder.
2. Include the MetricsObserver instance in your application’s ObserveFeature.
3. Register your ObserveFeature with your WebServer.

ObserveFeature observe = ObserveFeature.builder()
        .config(config.get("server.features.observe"))
        .addObserver(MetricsObserver.create())
        .build();

WebServer server = WebServer.builder()
        .config(Config.global().get("server"))
        .featuresDiscoverServices(false)
        .addFeature(observe)
        .routing(Main::routing)
        .build()
        .start();

The Helidon Metrics API defines the classes and interfaces for meter types and other related items.

The following table summarizes the meter types.

Each meter type has its own set of methods for updating and retrieving the value.

To register or look up meters programmatically, your service code uses the global MeterRegistry. Simply invoke Metrics.globalRegistry() to get a reference to the global meter registry.

To locate an existing meter or register a new one, your code:

1. Creates a builder of the appropriate type of meter, setting the name and possibly other characteristics of the meter.
2. Invokes the MeterRegistry.getOrCreate method, passing the builder.

The meter registry returns a reference to a previously-registered meter with the specified name and tags or, if none exists, a newly-registered meter. Your code can then operate on the returned meter as needed to record new measurements or retrieve existing data.

The example code in the section below illustrates how to register, retrieve, and update meters.

The neutral Helidon metrics API is an abstraction of common metrics behavior independent from any given implementation. As such, we intentionally excluded some implementation-specific behavior from the API.

Sometimes you might want access to methods that are present in a particular metrics implementation but not in the Helidon API. Helidon allows that via the unwrap method on the meter types and on their builders. Each full implementation of the Helidon meter types and their builders refers to a delegate meter or delegate builder internally. The unwrap method lets you obtain the delegate, cast to the type you want.

Of course, using this technique binds your code to a particular metrics implementation.

The Wrapper interface declares the unwrap method which accepts a class parameter to which the delegate is cast. You can then invoke any method declared on the implementation-specific type.

The following example, based on the Helidon SE QuickStart application, shows how to register and update a new Counter in application code. The counter tracks the number of times any of the service endpoints is accessed.

public class GreetService implements HttpService {

    private final Counter accessCtr = Metrics.globalRegistry() 
            .getOrCreate(Counter.builder("accessctr")); 

    @Override
    public void routing(HttpRules rules) {
        rules
                .any(this::countAccess) 
                .get("/", this::getDefaultMessageHandler)
                .get("/{name}", this::getMessageHandler)
                .put("/greeting", this::updateGreetingHandler);

    }

    void countAccess(ServerRequest request,
                     ServerResponse response) {

        accessCtr.increment(); 
        response.next();
    }

    void getDefaultMessageHandler(ServerRequest request,
                                  ServerResponse response) {
        // ...
    }

    void getMessageHandler(ServerRequest request,
                           ServerResponse response) {
        // ...
    }

    void updateGreetingHandler(ServerRequest request,
                               ServerResponse response) {
        // ...
    }
}

• Get the global meter registry.
• Create (or find) a counter named "accessctr" in the global registry.
• Route every request to the countAccess method.
• Increment the access counter for every request.

Perform the following steps to see the new counter in action.

mvn package
java -jar target/helidon-quickstart-se.jar

curl 'http://localhost:8080/observe/metrics?scope=application' 

# HELP accessctr_total
# TYPE accessctr_total counter
accessctr_total{scope="application",} 0.0 

• Access the metrics endpoint, selecting only application meters.
• Note the counter is zero; we have not accessed a service endpoint yet.

curl http://localhost:8080/greet

{"message":"Hello World"}

curl 'http://localhost:8080/observe/metrics?scope=application'

# HELP accessctr_total
# TYPE accessctr_total counter
accessctr_total{scope="application",} 1.0 

• The counter now reports 1, reflecting our earlier access to the /greet endpoint.

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

• Choose whether to collect extended key performance indicator metrics.

Disable Metrics Subsystem

server:
  features:
    observe:
      observers:
        metrics:
          enabled: false

Collecting Basic and Extended Key Performance Indicator (KPI) Meters

server:
  features:
    observe:
      observers:
        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

routing
        .addFeature(PrometheusSupport.create())
        .register("/myapp", new MyService());