DOCS: 4.X Metrics SE and MP

[ljamen]

Environment Details

• Helidon Version: 4.x
• Helidon SE or Helidon MP
• JDK version:
• OS:
• Docker version (if applicable):

---

Create Metrics Guide for Nima
Create Metrics article for Nima
Update Metrics Guide for MP
Update Metrics article for MP

Migration Impact

SE Metrics API

The Helidon neutral metrics API is completely different from the MicroProfile Metrics API which was used in Helidon 3.x SE.
Here are some of the key changes:

• Supported meter types: Counter, Gauge, DistributionSummary (histogram), Timer.
  • To migrate a 3.x ConcurrentGauge use a Gauge.
  • To migrate a 3.x SimpleTimer use a Timer.
  • To migrate a 3.x Meter consider using a Counter and aggregating rate statistics using the metrics back-ends.
• Scope (formerly registry type) is now an attribute of each meter. Helidon continues to provide three built-in scopes--application, base, and vendor--but applications can create their own custom scopes by setting the scope on the meter builder used to register or look up a meter.
• Helidon uses a single global MeterRegistry which holds all meters (instead of a separate registry for each scope), accessible using Metrics.globalRegistry().
• To register a new meter or retrieve a previously-registered one, create a Builder of the relevant meter type and then invoke Metrics.globalRegistry().getOrCreate(builder). For example:

  Counter myCounter = Metrics.globalRegistry().getOrCreate(Counter.builder("myCounter"));
  

  The builder allows you to assign a scope, a description, and any meter-dependent attributes.

SE Packaging

• Declaring the following dependency is sufficient for your app to use the neutral metrics API, include a full-featured implementation of the API, and support the metrics endpoint for retrieving meter data:

  <dependency>
      <groupId>io.helidon.webserver.observe</groupId>
      <artifactId>helidon-webserver-observe-metrics</artifactId>
  </dependency>
  

  Some developers prefer to add an explicit dependency on any artifact the code directly uses. If you want to explicitly declare a dependency on the metrics API, add the following:

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

SE Observability API and auto-discovery

The metrics subsystem is part of the Helidon observability family. As such, if you add the dependency above Helidon automatically discovers and activates the metrics observer so the metrics endpoint works (see below).

Alternatively, your code can exercise finer control over which observers (metrics, health, etc.) are activated in your server. How you do this has changed in Helidon 4.0. See the metrics and observability documentation pages, the metrics SE examples, and the JavaDoc for more details.

SE Metrics Endpoint

• The metrics subsystem is part of the Helidon observability family, so the default web context for the metrics endpoint is now /observe/metrics.
• To retrieve meters by scope, use a query parameter:

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

• To retrieve meters by name, use query parameters for the scope and name:

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

• The histogram output format (timers, distribution summaries) has changed slightly. Because developers can now specify the percentile values, the JSON keys for the percentiles (formerly the fixed set p50, p75, p95, p98, p99, p999) must vary and are now (for example) p0.50, p0.75, etc.

MP Metrics API

Helidon 4.0 supports MicroProfile Metrics 5.0 which contains quite a few changes from earlier MP metrics releases.

This section of the MP metrics doc summarizes the changes: https://download.eclipse.org/microprofile/microprofile-metrics-5.0.1/microprofile-metrics-spec-5.0.1.html#release_notes_5_0

Some highlights:

• ConcurrentGauge, SimpleTimer, and Meter metrics are gone. Use Gauge and Timer respectively instead. For Meter consider using a Counter and dealing with aggregating statistics using the downstream backend(s) which process the metrics output.
• The metrics metadata no longer contains a type or a display name.
• Permits custom scopes in addition to application, vendor, and base.
• Use query parameters instead of subpaths to retrieve by scope (curl 'http://localhost:8080/metrics?scope=application'). (Helidon continues to support subpaths for backward compatibility as a deprecated feature.)