Helidon Metrics API module

Intended audience

This informal document is intended for developers of Helidon components who are converting a metrics-dependent component to be metrics-capable instead.

Developers of new metrics-capable components should see the Helidon SE metrics guide (part 2) on developing metrics-capable compoments.

Overview

Helidon SE provides these related metrics components:

• helidon-metrics - The full-featured implementation of Helidon SE metrics and the support for the web service endpoint /metrics.
• helidon-metrics-api - New component, containing the public interface to Helidon SE metrics for Helidon SE apps and components. This component also includes "no-op" implementations of those interfaces which allow apps and components to create, register, look-up, and remove metrics in metrics registries. The implementations of metric types (counters, timers, etc.) in this component do not update.
• helidon-metrics-service-api - New component, containing the public interface to support for the metrics endpoint.

The helidon-metrics-api module contains interfaces for RegistryFactory and MetricsSupport which are API-compatible with their counterpart classes in helidon-metrics. With minimal coding changes, components can be converted to become metrics-capable.

Step-by-step Conversion

See docs/se/guides/_metrics-capable-components.adoc (the public documentation).

Change pom.xml

Change the pom.xml of the component to depend on helidon-metrics-api instead of helidon-metrics.

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

Change imports

Change imports of io.helidon.microprofile.metrics.RegistryFactory to io.helidon.metrics.api. RegistryFactory.

The interfaces in the new module are API-compatible with their counterparts in helidon-metrics so existing code that works with the existing RegistryFactory should compile and run just the same as before.

Update the builder for your component

1. Add a private field for the component metrics settings:

   private CompomentMetricsSettings.Builder componentMetricsSettingsBuilder = 
                   CompomentMetricsSettings.builder();
   

2. Add a setter for that field.

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

3. Add or augment a setter for Config so it includes the following code or the equivalent:

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

Update the constructor

1. Get the correct RegistryFactory implementation, using the component settings:

   RegistryFactory rf = 
           RegistryFactory.getInstance(builder.componentMetricsSettingsBuilder.build());
   

2. For whichever registry type or types your component uses, get and save the instances using (for example)

   MetricRegistry appRegistry = rf.getRegistry(MetricRegistry.Type.APPLICATION);
   

Use the saved registries

Expose those registries to the rest of your component and use them however your component requires.

You do not have to change any of the component code that registers, looks up, removes, or updates metrics.

Other topics

Component documentation

Consider enhancing your component's documentation to cover these topics.

1. Configuration

   Many components have their own settings, assignable via the builder and configuration. Add to or create a config format--and document it--for your component that includes a metrics section. This corresponds to the new ComponentMetricsSettings interface.

   Explain in your documentation how applications that depend on your component or users who package or deploy it can control whether your component's metrics features are enabled or disabled, for example using the config setting utilComponent.metrics.enabled=false.

2. Packaging

   Your component cannot update live metrics unless the Helidon metrics implementation in helidon-metrics is on the path at runtime. Your own component depends on the API, not the full metrics implementation in helidon-metrics.

   Whoever uses your component in an app or packages and deploys your component needs to be aware that--if they want metrics to work--they need to make sure the metrics implementation is available at runtime. As long as some Maven artifact in the stack has a runtime or stronger dependency on helidon-metrics (and if metrics is enabled via config or settings), then Helidon can activate the full-featured metrics.

The public doc contains a section about this. Your component's doc can link to that.