Allow metrics-capable components to work in absence of full-featured metrics (helidon-io#3441)

* Allow metrics-capable components to be written and executed without caring whether full-featured metrics are on the runtime path and enabled

Signed-off-by: tim.quinn@oracle.com <tim.quinn@oracle.com>

Author: tjquinno

bom/pom.xml

@@ -532,6 +532,16 @@
                 <artifactId>helidon-metrics</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.helidon.metrics</groupId>
+                <artifactId>helidon-metrics-api</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.helidon.metrics</groupId>
+                <artifactId>helidon-metrics-service-api</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.helidon.metrics</groupId>
                 <artifactId>helidon-metrics-trace-exemplar</artifactId>

docs/common/guides/metrics.adoc

@@ -68,6 +68,15 @@ The following example will demonstrate how to use the built-in metrics.  All exa
 from the root directory of your project (helidon-quickstart-{lower-case-flavor}).
 // end::using-built-in-metrics-intro[]
 
+// tag::metrics-dependency[]
+----
+<dependency>
+    <groupId>io.helidon.metrics</groupId>
+    <artifactId>helidon-metrics</artifactId>
+</dependency>
+----
+// end::metrics-dependency[]
+
 // tag::build-and-run-intro[]
 
 [source,bash,subs="attributes+"]
@@ -164,6 +173,51 @@ curl -H "Accept: application/json"  http://localhost:8080/metrics/vendor/request
 NOTE: You cannot get the individual fields of a metric. For example, you cannot target http://localhost:8080/metrics/vendor/requests.meter.count.
 // end::get-single-metric[]
 
+// tag::controlling[]
+// tag::controlling-intro[]
+
+=== Controlling Metrics Behavior
+You can control how metrics behaves in several ways by adding a `metrics` section to your application configuration. You can:
+
+*  disable metrics entirely,
+*  disable the use of metrics from individual components, and
+*  control the key performance indicator metrics which Helidon collects.
+
+// end::controlling-intro[]
+
+// tag::enabling-disabling-whole-intro[]
+==== Enabling and Disabling Metrics as a Whole
+By default, if your application depends on the `helidon-metrics` Maven module then full-featured metrics are enabled.
+You can disable metrics entirely using configuration:
+[source,properties]
+.Configuration properties file disabling metrics
+----
+metrics.enabled=false
+----
+// end::enabling-disabling-whole-intro[]
+
+// tag::enabling-disabling-whole-summary[]
+With metrics disabled, Helidon never updates any metrics and the `/metrics` endpoints respond with `404` plus a message that metrics are disabled.
+// end::enabling-disabling-whole-summary[]
+
+// tag::controlling-by-component-intro[]
+==== Enabling and Disabling Metrics Usage by a Component
+Helidon contains several components and integrations which register and update metrics.
+Depending on how the component is written, you might be able to disable just that component's use of metrics:
+[source,properties]
+.Configuration properties file disabling a component's use of metrics
+----
+some-component.metrics.enabled=false
+----
+Check the documentation for a specific component to find out whether that component uses metrics and whether it allows you to disable that use.
+// end::controlling-by-component-intro[]
+
+// tag::controlling-by-component-summary[]
+If you disable a component's use of metrics, Helidon does not register the component's metrics in the visible metrics registries nor do those metrics ever update their values. The response from the `/metrics` endpoint excludes that component's metrics.
+
+Note that if you disable overall metrics, no component updates its metrics regardless of any component-level metrics settings.
+// end::controlling-by-component-summary[]
+
 // tag::KPI[]
 ==== Key Performance Indicator (KPI) Metrics
 Any time you include the Helidon metrics module in your application, Helidon tracks two basic performance indicator metrics:
@@ -185,23 +239,8 @@ You can enable and control these metrics using configuration:
 metrics.key-performance-indicators.extended = true
 metrics.key-performance-indicators.long-running.threshold-ms = 2000
 ----
-
-ifeval::["{h1Prefix}" == "SE"]
-Your Helidon {h1Prefix} application can also control the behavior of the KPI metrics programmatically.
-
-. Prepare a `KeyPerformanceIndicatorSettings` object, using its builder, and then pass the builder when invoking the `MetricsSupport.Builder#keyPerformanceIndicatorMetricsSettings()` method.
-. Prepare a `Config` object and pass it to the `MetricsSupport.Builder#keyPerformanceIndicatorMetricsConfig()` method.
-+
-[source,properties]
-+
-.Example KPI metrics config fragment
-----
-extended = true
-long-running.threshold-ms = 2000
-----
-endif::[]
-
 // end::KPI[]
+// end::controlling[]
 
 // tag::metrics-metadata[]
 === Metrics Metadata

docs/mp/guides/05_metrics.adoc

@@ -85,6 +85,8 @@ You can see the results in the sample output shown in earlier example runs.
 
 include::{metrics-common}[tag=KPI]
 
+include::{metrics-common}[tag=controlling]
+
 include::{metrics-common}[tag=metrics-metadata]
 
 === Application-Specific Metrics Data

docs/se/guides/05_metrics.adoc

@@ -23,7 +23,7 @@
 :common-page-prefix-inc: ../../shared/common_prereqs/common_prereqs.adoc
 :common-guides: ../../common/guides
 :metrics-common: {common-guides}/metrics.adoc
-:javadoc-base-url-api: {javadoc-base-url}io.helidon.metrics/io/helidon/metrics
+:javadoc-base-url-api: {javadoc-base-url}io.helidon.metrics.api/io/helidon/metrics/api
 :metrics-support-builder-javadoc: {javadoc-base-url-api}/MetricsSupport.Builder.html
 :lower-case-flavor: se
 :intro-project-name: {h1Prefix}
@@ -37,14 +37,7 @@ The generated source code is already configured for both metrics and health chec
 
 [source,xml]
 .Notice that the metrics dependency is already in the project's pom.xml file:
-----
-<dependency>
-    <groupId>io.helidon.metrics</groupId>
-    <artifactId>helidon-metrics</artifactId>
-</dependency>
-----
-
-
+include::{metrics-common}[tag=metrics-dependency]
 [source,java]
 .Replace the `Main.createRouting` method with the following code:
 ----
@@ -89,9 +82,96 @@ include::{metrics-common}[tag=vendor-metrics-json-output]
 
 include::{metrics-common}[tag=get-single-metric]
 
+////
+Controlling Metrics section
+
+For the SE guide, we stitch in the shared content about controlling metrics around SE-specific content that is not shared. It makes for a bit choppy-looking source here but it renders just fine and lets us easily share the content that's common between SE and MP.
+
+////
+include::{metrics-common}[tag=controlling-intro]
+
+Your Helidon SE application can also control metrics programmatically as described in the following sections.
+
+include::{metrics-common}[tag=enabling-disabling-whole-intro]
+
+A Helidon SE application can disable metrics programmatically.
+[source,java]
+.Disable all metrics behavior
+----
+import io.helidon.metrics.api.MetricsSettings;
+import io.helidon.metrics.serviceapi.MetricsSupport;
+import io.helidon.metrics.api.RegistryFactory;
+...
+
+    MetricsSettings metricsSettings = MetricsSettings.builder()
+            .enabled(false)
+            .build(); // <1>
+
+    MetricsSupport metricsSupport = MetricsSupport.create(metricsSettings); // <2>
+
+    RegistryFactory registryFactory = RegistryFactory.getInstance(metricsSettings); // <3>
+----
+<1> Create a link:{javadoc-base-url-api}/MetricsSettings.html[`MetricsSettings]` instance (via its link:{javadoc-base-url-api}/MetricsSettings.Builder.html[`Builder`]) with metrics disabled.
+<2> Get a link:{javadoc-base-url-api}/MetricsSupport.html[`MetricsSupport]` service (usable in setting routing rules) that responds
+to the `/metrics` endpoint with `404` and an explanatory message.
+<3> Get a link:{javadoc-base-url-api}/RegistryFactory.html[`RegistryFactory]` instance that provides `MetricRegistry` instances which register
+ no-op metric objects (counters, timers, etc.).
+
+These builders and interfaces also have methods which accept `Config` objects representing the `metrics` node from the application configuration.
+
+include::{metrics-common}[tag=enabling-disabling-whole-summary]
+
 include::{metrics-common}[tag=KPI]
 
-Your Helidon SE application can also enable or disable the extended KPI metrics and control the long-running request threshold using methods on the link:{metrics-support-builder-javadoc}[MetricsSupport.Builder] class.
+Your Helidon SE application can also control the KPI settings programmatically.
+[source,java]
+.Assign KPI metrics behavior from code
+----
+import io.helidon.metrics.api.KeyPerformanceIndicatorMetricsSettings;
+import io.helidon.metrics.api.MetricsSettings;
+import io.helidon.metrics.serviceapi.MetricsSupport;
+import io.helidon.metrics.api.RegistryFactory;
+...
+
+    KeyPerformanceIndicatorMetricsSettings.Builder kpiSettingsBuilder =
+        KeyPerformanceIndicatorMetricsSettings.builder()
+            .extended(true)
+            .longRunningThresholdMs(2000); <1>
+
+    MetricsSettings metricsSettings = MetricsSettings.builder()
+            .keyPerformanceIndicatorSettings(kpiSettingsBuilder)
+            .build(); // <2>
+----
+<1> Create a link:{javadoc-base-url-api}/KeyPerformanceIndicatorMetricsSettings.html[`KeyPerformanceIndicatorMetricsSettings]` instance (via its link:{javadoc-base-url-api}/KeyPerformanceIndicatorMetricsSettings.Builder.html[`Builder`]) with non-default values.
+<2> Create a link:{javadoc-base-url-api}/MetricsSettings.html[`MetricsSettings]` instance reflecting the KPI settings.
+
+include::{metrics-common}[tag=controlling-by-component-intro]
+
+Your Helidon SE application can disable a metrics-capable component's use of metrics programmatically.
+
+[source,java]
+.Disable metrics use in a metrics-capable component
+----
+import io.helidon.metrics.api.ComponentMetricsSettings;
+...
+
+    ComponentMetricsSettings.Builder componentMetricsSettingsBuilder = ComponentMetricsSettings.builder()
+            .enabled(false); // <1>
+
+    SomeService someService = SomeService.builder()
+            ...
+            .componentMetricsSettings(componentMetricsSettingsBuilder)
+            ...
+            .build(); // <2>
+
+----
+<1> Create a link:{javadoc-base-url-api}/ComponentMetricsSettings.html[`ComponentMetricsSettings]` instance (via its link:{javadoc-base-url-api}/ComponentMetricsSettings.Builder.html[`Builder`]) indicating that metrics usage should be disabled.
+<2> Create an instance of the service with its metrics usage disabled.
+
+include::{metrics-common}[tag=controlling-by-component-summary]
+
+
+// end of Controlling Metrics section
 
 include::{metrics-common}[tag=metrics-metadata]
 
@@ -654,6 +734,9 @@ curl -H "Accept: application/json"  http://localhost:8080/metrics/application
 
 include::{metrics-common}[tag=k8s-and-prometheus-integration]
 
+=== Advanced Topic: Metrics-capable Applications and Components
+Metrics-capable components are written to register and update metrics but can work even if the Helidon metrics implementation _is not_ on the runtime path. Please see this additional section on <<se/guides/_metrics-capable-components.adoc,Metrics-capable components>> which describes this feature.
+
 === Summary
 
 This guide demonstrated how to use metrics in a Helidon SE application using various combinations of