• The Helidon metrics API

  This API allows your code to register, look-up, remove, and update metrics using the RegistryFactory, MetricRegistry, and individual metrics interfaces.

• The Helidon metrics REST service API

  This API allows your code to set up and respond to the /metrics endpoint so clients can retreive metrics information.

• Implementations of the Helidon metrics API.

  Helidon provides two—​minimal and full-featured—​and selects which one to use at runtime, based on what components are present on the runtime path and whether metrics is configured to be enabled or disabled.

  By default, Helidon MP services use the full-featured implementation.

• Implementations of the Helidon metrics REST service API.

  Helidon provides two—​minimal and full-featured—​and selects which one to use at runtime.

  By default, Helidon MP apps which use metrics use the full-featured metrics REST service by default.

As you plan and write Helidon components and applications, you make some choices about exactly how your code will use metrics. This document gives some background information, describes each option and its effect, and provides some code examples.

We can place each Helidon component and Helidon application into one of three categories based on how it relies on metrics. The type of module dictates the compile-time dependency you declare in the project pom.xml.

Whenever possible, if your component or application uses metrics, then write it as metrics-capable code.

Helidon provides two metrics implementations:

• Full-featured metrics allows registering, removing, and updating metrics and observing metrics' changing values. The helidon-metrics component contains full-featured metrics.

• Minimal metrics supports registering, removing, and updating metrics. The metrics objects provided by the minimal implementation are no-ops: their values never change. The minimal implementation is part of the helidon-metrics-api component.

Any code compiled with helidon-metrics-api can assume that the runtime path will include the minimal implementation.

Both implementations support all the operations of the RegistryFactory and the MetricRegistry. The full implementation provides fully-functional metrics instances (counters, timers, etc.). In the minimal implementations, metrics do not update their values.

For Helidon to use the full implementation, two conditions must hold:

• The helidon-metrics component must be on the runtime path.

• Metrics must be enabled, using either a builder or configuration. (Enabled is the default.)

Otherwise, provided that the runtime path includes helidon-metrics-api, Helidon activates the minimal implementation.

Helidon includes two implementations of support for the metrics web service endpoint /metrics (or whatever context value is configured).

The full-service implementation sends responses which describe the metadata and current values for the metrics registered in metric registries. The helidon-metrics component contains this implementation.

The helidon-metrics-service-api component contains the API for the metrics web service support (the MetricsSupport interface) and also a minimal implementation. This implementation simply responds with 404 and an explanatory message that metrics are disabled.

Any code compiled with helidon-metrics-service-api can assume that the runtime path will contain the minimal implementation.

Helidon activates the full implementation if the runtime path includes the full implementation and metrics is configured as enabled; Helidon uses the minimal implementation otherwise.

Using configuration, your component can let end users control at runtime whether Helidon should use full-featured metrics. If an end user sets metrics.enabled to false, then Helidon activates the minimal metrics and metrics service implementations provided they are in the runtime path.

Further, users can set component-name.metrics.enabled to false which disables metrics for just that component so long as the component was written to check that setting and act on it accordingly.

Whoever packages and deploys your application or component can control what code will be on the runtime path and whether metrics is enabled or not. As a result, wherever possible, construct your modules which use metrics so that they do not make decisions based on the values of metrics; that is, design them to be metrics-capable, not metrics-dependent. Doing so allows your code to operate regardless of whether the full-featured metrics implementation is active at runtime.

Declaring Dependencies

The way you write a metrics-capable module depends on whether it is a component (that is, not an application) or an application.

Writing a Helidon MP Application

Packaging a Metrics-Capable Helidon MP Application

<dependency>
    <groupId>io.helidon.microprofile.bundles</groupId>
    <artifactId>helidon-microprofile</artifactId>
    <exclusions>
        <exclusion>
            <groupId>io.helidon.metrics</groupId>
            <artifactId>helidon-metrics</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Writing a Non-Application Component

import io.helidon.config.Config;
import io.helidon.metrics.api.ComponentMetricsSettings;
import io.helidon.metrics.api.MetricsSettings;
import io.helidon.metrics.api.RegistryFactory;

import org.eclipse.microprofile.metrics.MetricRegistry;

public class UtilComponent {

    private final MetricRegistry metricRegistry; 

    public static class Builder implements io.helidon.common.Builder<UtilComponent> { 
        private ComponentMetricsSettings.Builder componentMetricsSettingsBuilder = ComponentMetricsSettings.builder();

        public Builder componentMetricsSettings(ComponentMetricsSettings.Builder componentMetricsSettingsBuilder) { 
            this.componentMetricsSettingsBuilder = componentMetricsSettingsBuilder;
            return this;
        }

        public Builder config(Config componentConfig) { 
            componentConfig
                .get(ComponentMetricsSettings.Builder.METRICS_CONFIG_KEY)
                .as(ComponentMetricsSettings::create)
                .ifPresent(this::componentMetricsSettings);
            return this;
        }

        public UtilComponent build() {
            return new UtilComponent(this);
        }
    }

    private UtilComponent(Builder builder) {
        metricRegistry = RegistryFactory
                .getInstance(builder.componentMetricsSettingsBuilder.build())
                .getRegistry(MetricRegistry.Type.VENDOR); 
    }

    MetricRegistry metricRegistry() { 
        return metricRegistry;
    }
}

By writing a metrics-capable app or component, you give packagers and deployers of your code the flexibility to include or exclude the full metrics implementation at runtime as they see fit.

Because your one module works correctly in either environment:

• The consumers of your app benefit by not needing to understand and choose between two different implementations of your module, or having to add both your main module and an optional add-on which adds metrics support to your module.

• You benefit by writing and maintaining a single module, not two: one that is metrics-independent and one that is metrics-dependent.