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 supports meters inspired by Micrometer and summarized in the following table:

Helidon distinguishes among scopes, or categories, 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

# HELP classloader_loadedClasses_count Displays the number of classes that are currently loaded in the Java virtual machine.
# TYPE classloader_loadedClasses_count gauge
classloader_loadedClasses_count{scope="base",} 5297.0

See the summary of the OpenMetrics and Prometheus Format for more information.

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.

OpenMetrics and Prometheus Format

JSON Format

{
  "application": {  
    "getTimer": {
      "type": "timer",
      "unit": "seconds",
      "description": "Timer for getting the default greeting"
    }
  },
  "vendor": {       
    "requests.count": {
      "type": "counter",
      "description": "Each request (regardless of HTTP method) will increase this counter"
    }
  },
  "base": {         
    "cpu.systemLoadAverage": {
      "type": "gauge",
      "description": "Displays the system load average for the last minute."
    },
    "classloader.loadedClasses.count": {
      "type": "gauge",
      "description": "Displays the number of classes that are currently loaded in the Java virtual machine."
    }
  }
}

{
  "cpu.systemLoadAverage": {
    "type": "gauge",
     "description": "Displays the system load average for the last minute."
  },
  "classloader.loadedClasses.count": {
    "type": "gauge",
    "description": "Displays the number of classes that are currently loaded in the Java virtual machine."
  }
}

"requests.count": 5

"getTimer": {
  "count": 3,
  "max": 0.0030455,
  "mean": 0.0011060836666666666,
  "elapsedTime": 0.003318251,
  "p0.5": 0.000151552,
  "p0.75": 0.003141632,
  "p0.95": 0.003141632,
  "p0.98": 0.003141632,
  "p0.99": 0.003141632,
  "p0.999": 0.003141632
}

"requests.count": {
  "type": "counter",
  "description": "Each request (regardless of HTTP method) will increase this counter"
    }

"getTimer": {
  "type": "timer",
  "unit": "seconds",
  "description": "Timer for getting the default greeting"
}

metrics:
  timers:
    json-units-default: units 

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.

To date Helidon 4 releases have implemented the system-provided meter gc.time as a counter. In fact, a gauge is more suitable for the approximate time the JVM has spent doing garbage collection.

Helidon 4.3.3 continues to use a counter by default to preserve backward compatibility, but you can choose to use a gauge by setting the configuration property metrics.gc-time-type to gauge. You can also set the config property to counter which is the default.

Why should you care? In fact, this distinction might not make a difference for many users. But for others the differences between the programmatic APIs for Counter and Gauge would affect application code that works directly with the gc-time meter. Further, the difference in output—​particularly in the OpenMetrics/Prometheus format—​might affect their application or downstream monitoring tools.

The ability to choose the meter type for gc.time is deprecated and is planned for removal in a future major release of Helidon at which time Helidon will always use a gauge.

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 report virtual threads meters.

• Choose whether to collect extended key performance indicator metrics.

Disable Metrics Subsystem

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

Configuring Virtual Threads Meters

metrics:
  virtual-threads:
    enabled: true

metrics:
  virtual-threads:
    pinned:
      threshold: PT0.100S

Collecting Basic and Extended Key Performance Indicator (KPI) Meters

server:
  features:
    observe:
      observers:
        metrics:
          key-performance-indicators:
            extended: true
            long-running:
              threshold-ms: 2000

Micrometer Metrics concepts documentation

OpenMetrics format

Prometheus exposition format

• 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());