Implement Micrometer integration, with some new abstractions for interceptors and retrofit to MP metrics

bom/pom.xml

@@ -583,6 +583,16 @@
                 <artifactId>helidon-common-context</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.helidon.service-common</groupId>
+                <artifactId>helidon-service-common-rest</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.helidon.service-common</groupId>
+                <artifactId>helidon-service-common-rest-cdi</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
 
             <!-- db client -->
             <dependency>
@@ -861,6 +871,16 @@
                 <artifactId>helidon-integrations-common-rest</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.helidon.integrations</groupId>
+                <artifactId>helidon-integrations-micrometer</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.helidon.integrations</groupId>
+                <artifactId>helidon-integrations-micrometer-cdi</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
             <!-- OpenAPI support -->
             <dependency>
                 <groupId>io.helidon.openapi</groupId>

common/common/src/main/java/io/helidon/common/FeatureCatalog.java

@@ -343,6 +343,15 @@ final class FeatureCatalog {
                     .experimental(true)
         );
 
+        addSe("io.helidon.integrations.micrometer",
+                    "Micrometer",
+                    "Micrometer integration",
+                    "Micrometer");
+        addMp("io.helidon.integrations.micrometer.cdi",
+                "Micrometer CDI",
+                "Micrometer CDI integration",
+                "Micrometer-CDI");
+
         /*
          * Common modules
          */

dependencies/pom.xml

@@ -91,6 +91,7 @@
         <version.lib.logback>1.2.3</version.lib.logback>
         <version.lib.mariadb-java-client>2.6.2</version.lib.mariadb-java-client>
         <version.lib.maven-wagon>2.10</version.lib.maven-wagon>
+        <version.lib.micrometer>1.6.5</version.lib.micrometer>
         <version.lib.micronaut>2.2.0</version.lib.micronaut>
         <version.lib.micronaut.data>2.2.0</version.lib.micronaut.data>
         <version.lib.micronaut.sql>3.3.1</version.lib.micronaut.sql>
@@ -553,6 +554,18 @@
                 <version>${version.lib.database.messaging}</version>
             </dependency>
 
+            <!-- Micrometer related -->
+            <dependency>
+                <groupId>io.micrometer</groupId>
+                <artifactId>micrometer-core</artifactId>
+                <version>${version.lib.micrometer}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.micrometer</groupId>
+                <artifactId>micrometer-registry-prometheus</artifactId>
+                <version>${version.lib.micrometer}</version>
+            </dependency>
+
             <!-- Microprofile related -->
             <dependency>
                 <groupId>org.eclipse.microprofile.config</groupId>

docs/mp/metrics/02_micrometer.adoc

@@ -0,0 +1,87 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2021 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+///////////////////////////////////////////////////////////////////////////////
+
+= Micrometer Metrics
+:description: Helidon Micrometer integration
+:keywords: micrometer, helidon, metrics, integration, microprofile
+:javadoc-base-url-api: {javadoc-base-url}io.helidon.integrations.micrometer/io/helidon/integrations/micrometer
+:h1Prefix: MP
+:common-page-prefix-inc: ../../shared/metrics/micrometer_shared.adoc
+:isMP: true
+
+
+include::{common-page-prefix-inc}[tags=intro]
+
+include::{common-page-prefix-inc}[tags=prereq]
+
+== Using Micrometer in Your Application
+Add the Micrometer `@Timed` and `@Counted` annotations to methods in your application.
+
+The examples below enhance the Helidon MP QuickStart application to track (by time and invocation count) all `GET` methods and to count all requests for a personalized greeting.
+
+=== Add Micrometer annotations
+
+[source,java]
+.Adding Micrometer annotations to JAX-RS resource `GET` methods
+----
+import io.micrometer.core.annotation.Counted;
+import io.micrometer.core.annotation.Timed;
+    // <1>
+    private static final String PERSONALIZED_GETS_COUNTER_NAME = "personalizedGets";
+    private static final String PERSONALIZED_GETS_COUNTER_DESCRIPTION = "Counts personalized GET operations";
+    private static final String GETS_TIMER_NAME = "allGets";
+    private static final String GETS_TIMER_DESCRIPTION = "Tracks all GET operations";
+
+    @GET
+    @Produces(MediaType.APPLICATION_JSON)
+    @Timed(value = GETS_TIMER_NAME, description = GETS_TIMER_DESCRIPTION, histogram = true) // <2>
+    public JsonObject getDefaultMessage() {
+        return createResponse("World");
+    }
+
+    @Path("/{name}")
+    @GET
+    @Produces(MediaType.APPLICATION_JSON)
+    @Counted(value = PERSONALIZED_GETS_COUNTER_NAME, description = PERSONALIZED_GETS_COUNTER_DESCRIPTION) // <3>
+    @Timed(value = GETS_TIMER_NAME, description = GETS_TIMER_DESCRIPTION, histogram = true) // <2>
+    public JsonObject getMessage(@PathParam("name") String name) {
+        return createResponse(name);
+    }
+----
+<1> Declare constants used in annotating multiple methods.
+<2> Use `@Timed` to time and count both `GET` methods.
+<3> Use `@Counted` to count the accesses to the `GET` method that returns a personalized greeting.
+
+=== Using the Helidon-provided Micrometer `MeterRegistry` from Code
+
+In addition to annotating your methods, you can create, look up, and update metrics explicitly in your code.
+
+Add the following injection to a bean:
+[source,java]
+.Inject the `MeterRegistry`
+----
+@Inject
+private MeterRegistry registry;
+----
+Helidon automatically injects a reference to the `MeterRegistry` it manages into your code. Your code can use the normal Micrometer API with this registry to create, find, update, and even delete meters.
+
+include::{common-page-prefix-inc}[tags=overriding-intro;overriding-using-config]
+
+include::{common-page-prefix-inc}[tags=accessing-endpoint-intro]
+
+Within Helidon, each type of meter registry is paired with code that examines the incoming HTTP request and decides whether the request matches up with the associated meter registry. The first pairing that accepts the request returns the response.

docs/se/metrics/02_micrometer.adoc

@@ -0,0 +1,178 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2021 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+///////////////////////////////////////////////////////////////////////////////
+
+= Micrometer Metrics
+:description: Helidon Micrometer integration
+:keywords: micrometer, helidon, metrics, integration
+:javadoc-base-url-api: {javadoc-base-url}io.helidon.integrations.micrometer/io/helidon/integrations/micrometer
+:h1Prefix: SE
+:common-page-prefix-inc: ../../shared/metrics/micrometer_shared.adoc
+:isSE: true
+
+include::{common-page-prefix-inc}[tags=intro]
+
+include::{common-page-prefix-inc}[tags=prereq]
+
+== Using Micrometer in Your Application
+You need to make two types of changes to your application to use Helidon SE integration with Micrometer:
+
+. Register an instance of link:{javadoc-base-url-api}/MicrometerSupport.html[`MicrometerSupport`] with the web server.
+. Create  meters using the meter registry which `MicrometerSupport` manages and update those meters.
+
+=== Register an Instance of `MicrometerSupport` with the Web Server
+
+[source,java]
+.Initialize Micrometer support
+----
+import io.helidon.integrations.micrometer.MicrometerSupport;
+//...
+MicrometerSupport micrometerSupport = MicrometerSupport.create(); // <1>
+
+Routing.builder()
+                .register(micrometerSupport) // <2>
+                .register("/myapp", new MyService(micrometerSupport.registry())) // <3>
+                .build();
+----
+<1> Create the `MicrometerSupport` instance, using the default built-in Prometheus meter registry.
+<2> Register the support instance as a service; by default, `MicrometerSupport` exposes the endpoint as `/micrometer`.
+<3> Pass the `MicrometerSupport` object's meter registry to your service for use in creating and updating meters.
+
+=== Create and Update Meters in your Application Service
+
+[source,java]
+.Define and use a `Counter`
+----
+import io.micrometer.core.instrument.Counter;
+
+public class MyService implements Service {
+
+    private final Counter requestCounter;
+
+    public MyService(MicrometerMeterRegistry registry) {
+        requestCounter = registry.counter("allRequests"); // <1>
+        // ...
+    }
+
+    @Override
+    public void update(Routing.Rules rules) {
+        rules
+            .any(this::countRequests) // <2>
+            .get("/", this::myGet);
+    }
+
+    private void countRequests(ServerRequest request, ServerResponse response) {
+        requestCounter.increment(); // <3>
+        request.next();
+    }
+}
+----
+<1> Use the Micrometer meter registry to create the request counter.
+<2> Add routing for any request to invoke the method which counts requests by updating the counter.
+<3> Update the counter and delegate the rest of the request processing to the next handler in the chain.
+
+The example above enrolls the built-in Prometheus meter registry with the default Prometheus registry configuration.
+You can change the default setup for built-in registries, and you can enroll other meter registries your application
+creates itself.
+
+include::{common-page-prefix-inc}[tag=overriding-intro]
+
+You can override these defaults in either of two ways:
+
+* Using the link:{javadoc-base-url-api}/MicrometerSupport.Builder.html[`MicrometerSupport.Builder`] class
+* Using configuration
+
+==== Using `MicrometerSupport.Builder`
+Use the `MicrometerSupport.Builder` class to set up Micrometer support however your application needs.
+
+The builder lets you:
+
+* Provide your own Micrometer meter registry configuration that `MicrometerSupport` uses to create a built-in meter
+registry, or
+* Instantiate a Micrometer meter registry yourself, configured however you want, and add it to the `MicrometerSupport`
+object's collection of meter registries
+
+[source,java]
+.Overriding defaults for built-in meter registries using `MicrometerSupport.Builder`
+----
+PrometheusConfig myPrometheusConfig = ...; // <1>
+MicrometerSupport support = MicrometerSupport.builder()
+                .enrollBuiltInRegistry( // <2>
+                        MicrometerSupport.BuiltInRegistryType.PROMETHEUS,
+                        myPrometheusConfig)
+                .build();
+----
+<1> Create the meter registry configuration however you need.
+<2> Enroll the `PROMETHEUS` built-in registry type with your custom configuration.
+
+
+==== Using Configuration
+include::{common-page-prefix-inc}[tag=overriding-using-config]
+
+
+=== Enrolling other Micrometer meter registries
+To create additional types of registries and enroll them with `MicrometerSupport`, you need to:
+
+. Write a `Handler` +
++
+Each meter registry has its own way of producing output.
+Write your handler so that it has a reference to the meter registry it should use and so that
+its `accept` method sets the payload in the HTTP response using the registry's mechanism for creating output.
+
+. Write a `Function` which accepts a `ServerRequest` and returns an `Optional<Handler>` +
++
+In general, your function looks at the request--the `Content-Type`, query parameters, etc.--to
+decide whether your handler should respond to the request.
+If so, your function should instantiate your `Handler` and return an `Optional.of(theHandlerInstance)`;
+otherwise, your function should return `Optional.empty()`. +
++
+When `MicrometerSupport` receives a request, it invokes the functions of all the enrolled registries,
+stopping as soon as one function provides a handler.
+`MicrometerSupport` then delegates to that handler to create and send the response.
+
+. Pass the `Handler` and `Function` to the `MicrometerSupport.enrollRegistry` method to enroll them +
++
+[source,java]
+.Creating and enrolling your own Micrometer meter registry
+----
+MeterRegistry myRegistry = new PrometheusMeterRegistry(myPrometheusConfig); // <1>
+MicrometerSupport support = MicrometerSupport.builder()
+                .enrollRegistry(myRegistry,
+                               request -> request // <2>
+                                    .headers()
+                                    .bestAccepted(MediaType.TEXT_PLAIN).isPresent()
+                                    ? Optional.of((req, resp) ->
+                                            resp.send(myRegistry.scrape())) // <3>
+                                    : Optional.empty())
+                .build();
+----
+<1> Create the meter registry. This example uses a Prometheus registry but it can be any extension of `MeterRegistry`.
+<2> Provide the function that checks if the link:{javadoc-base-url-webserver}/ServerRequest.html[`ServerRequest`]
+accepts content that your meter registry can produce (e.g., either `text/plain` or unspecified is normally an indication for Prometheus-style output)
+and returns the appropriate `Optional<link:{:javadoc-base-url-webserver}/Handler.html[``Handler``]>`.
+<3> A very simple in-line `Handler` that sets the response entity from the Prometheus registry's `scrape()` method.
+
+include::{common-page-prefix-inc}[tag=accessing-endpoint-intro]
+
+When `MicrometerSupport` receives a request at the endpoint, it looks for the first enrolled meter registry for which
+the corresponding `Function<ServerRequest, Optional<Handler>>` returns a non-empty `Handler`.
+Helidon invokes that `Handler` which must retrieve the metrics output from its meter registry and set
+and send the response.
+Note that the `Handler` which your function returns typically has a reference to the meter registry it will use
+in preparing the response.
+
+

docs/se/metrics/02_prometheus.adoc → docs/se/metrics/03_prometheus.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2019, 2020 Oracle and/or its affiliates.
+    Copyright (c) 2019, 2021 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.