Add support for MP Metrics 2.3 (#2245)

archetypes/bare-mp/src/main/resources/src/main/resources/META-INF/microprofile-config.properties

@@ -5,3 +5,6 @@ app.greeting=Hello
 # Microprofile server properties
 server.port=8080
 server.host=0.0.0.0
+
+# Change the following to true to enable the optional MicroProfile Metrics REST.request metrics
+metrics.rest-request.enabled=false

archetypes/database-mp/src/main/resources/src/main/resources/META-INF/microprofile-config.properties

@@ -9,3 +9,6 @@ javax.sql.DataSource.test.dataSource.password=
 # Microprofile server properties
 server.port=8080
 server.host=0.0.0.0
+
+# Change the following to true to enable the optional MicroProfile Metrics REST.request metrics
+metrics.rest-request.enabled=false

archetypes/quickstart-mp/src/main/resources/src/main/resources/META-INF/microprofile-config.properties

@@ -5,3 +5,6 @@ app.greeting=Hello
 # Microprofile server properties
 server.port=8080
 server.host=0.0.0.0
+
+# Turn on support for REST.request SimpleTimers for all JAX-RS endpoints
+metrics.rest-request.enabled=true

dependencies/pom.xml

@@ -82,7 +82,7 @@
         <version.lib.microprofile-config>1.4</version.lib.microprofile-config>
         <version.lib.microprofile-health>2.1</version.lib.microprofile-health>
         <version.lib.microprofile-jwt>1.1.1</version.lib.microprofile-jwt>
-        <version.lib.microprofile-metrics-api>2.2</version.lib.microprofile-metrics-api>
+        <version.lib.microprofile-metrics-api>2.3.2</version.lib.microprofile-metrics-api>
         <version.lib.microprofile-openapi-api>1.1.2</version.lib.microprofile-openapi-api>
         <version.lib.microprofile-fault-tolerance-api>2.0.2</version.lib.microprofile-fault-tolerance-api>
         <version.lib.microprofile-tracing>1.3.1</version.lib.microprofile-tracing>
@@ -656,6 +656,17 @@
                     </exclusion>
                 </exclusions>
             </dependency>
+            <dependency>
+                <groupId>org.eclipse.microprofile.metrics</groupId>
+                <artifactId>microprofile-metrics-optional-tck</artifactId>
+                <version>${version.lib.microprofile-metrics-api}</version>
+                <exclusions>
+                    <exclusion>
+                        <groupId>org.jboss.arquillian.junit</groupId>
+                        <artifactId>arquillian-junit-container</artifactId>
+                    </exclusion>
+                </exclusions>
+            </dependency>
             <dependency>
                 <groupId>org.eclipse.microprofile.metrics</groupId>
                 <artifactId>microprofile-metrics-api-tck</artifactId>

docs/mp/guides/05_metrics.adoc

@@ -82,6 +82,15 @@ curl http://localhost:8080/metrics
 [source,text]
 .Text response:
 ----
+# TYPE base_REST_request_total counter
+# HELP base_REST_request_total The number of invocations and total response time of RESTful resource methods since the start of the server.
+base_REST_request_total{class="io.helidon.examples.quickstart.mp.GreetResource",method="getDefaultMessage"} 0
+# TYPE base_REST_request_elapsedTime_seconds gauge
+base_REST_request_elapsedTime_seconds{class="io.helidon.examples.quickstart.mp.GreetResource",method="getDefaultMessage"} 0.0
+base_REST_request_total{class="io.helidon.examples.quickstart.mp.GreetResource",method="getMessage_java.lang.String"} 0
+base_REST_request_elapsedTime_seconds{class="io.helidon.examples.quickstart.mp.GreetResource",method="getMessage_java.lang.String"} 0.0
+base_REST_request_total{class="io.helidon.examples.quickstart.mp.GreetResource",method="updateGreeting_javax.json.JsonObject"} 0
+base_REST_request_elapsedTime_seconds{class="io.helidon.examples.quickstart.mp.GreetResource",method="updateGreeting_javax.json.JsonObject"} 0.0
 # TYPE base:classloader_current_loaded_class_count counter
 # HELP base:classloader_current_loaded_class_count Displays the number of classes that are currently loaded in the Java virtual machine.
 base:classloader_current_loaded_class_count 7511
@@ -104,6 +113,15 @@ curl -H "Accept: application/json"  http://localhost:8080/metrics
 ----
 {
   "base": {
+    "REST.request":
+      {
+        "count;class=io.helidon.examples.quickstart.mp.GreetResource;method=getDefaultMessage":0,
+        "elapsedTime;class=io.helidon.examples.quickstart.mp.GreetResource;method=getDefaultMessage":0.0,
+        "count;class=io.helidon.examples.quickstart.mp.GreetResource;method=getMessage_java.lang.String":0,
+        "elapsedTime;class=io.helidon.examples.quickstart.mp.GreetResource;method=getMessage_java.lang.String":0.0,
+        "count;class=io.helidon.examples.quickstart.mp.GreetResource;method=updateGreeting_javax.json.JsonObject":0,
+        "elapsedTime;class=io.helidon.examples.quickstart.mp.GreetResource;method=updateGreeting_javax.json.JsonObject":0.0
+      },
     "classloader.currentLoadedClass.count": 7534,
     "classloader.totalLoadedClass.count": 7538,
     "classloader.totalUnloadedClass.count": 1,
@@ -166,6 +184,19 @@ curl -H "Accept: application/json"  http://localhost:8080/metrics/vendor/grpc.re
 
 NOTE: You cannot get the individual fields of a metric. For example, you cannot target http://localhost:8080/metrics/vendor/grpc.requests.meter.count.
 
+==== Controlling `REST.request` metrics
+Helidon implements the optional family of metrics, all with the name `REST.request`, as described in the
+link:https://download.eclipse.org/microprofile/microprofile-metrics-2.3/microprofile-metrics-spec-2.3.html#_optional_rest[MicroProfile Metrics specification].
+Each instance is a `SimpleTimer` with tags `class` and `method` identifying exactly which REST endpoint Java
+method that instance measures.
+
+By default, Helidon MP does _not_ enable this feature.
+Enable it by editing your application configuration to set `metrics.rest-request.enabled` to `true`.
+
+Note that the applications you generate using the full Helidon archetype _do_ enable this feature in the
+generated config file.
+You can see the results in the sample output shown in earlier example runs.
+
 === Metrics metadata
 
 Each metric has associated metadata that describes:
@@ -222,11 +253,12 @@ Each metric annotation has mandatory and optional fields. The name field, for ex
 
 ==== Method level metrics
 
-There are three metrics that you can use by annotating a method:
+There are four metrics that you can use by annotating a method:
 
 1. `@Counted` - Register a `Counter` metric
 2. `@Timed` - Register a `Timer` metric
 3. `@Metered` - Register a `Meter` metric
+4. `@SimplyTimed` - Register a `SimpleTimer` metric
 
 The following example will demonstrate how to use the `@Counted` annotation to track the number of times
 the `/cards` endpoint is called.
@@ -312,8 +344,13 @@ You must use  `absolute=false` for class-level annotations.
 
 ==== Additional method-level metrics
 
-The `@Timed` and `@Metered` annotations can also be used with a method.  For the following example. you can just annotate the same method with these metrics.
-When using multiple annoations on a method, you *must* give the metrics different names as shown below.
+The `@Timed`, `@Metered`, and `@SimplyTimed` annotations can also be used with a method.  For the following example.
+you can just annotate the same method with `@Metered` and `@Timed`. These metrics collect significant
+information about the measured methods, but at a cost of some overhead and more complicated output.
+Use `@SimplyTimed` in cases where capturing the invocation count and the total elapsed time
+spent in a block of code is sufficient.
+
+Note that when using multiple annotations on a method, you *must* give the metrics different names as shown below.
 
 [source,java]
 .Update the `GreetingCards` class with the following code:

docs/se/guides/05_metrics.adoc

@@ -429,6 +429,8 @@ curl -H "Accept: application/json"  http://localhost:8080/metrics/application
 
 ==== Timer metric
 
+(See also <<#simple_timer_metric,Simple timer metric>>.)
+
 The `Timer` metric aggregates durations, provides timing statistics, and includes throughput statistics
 using an internal `Meter` metric. The `Timer` measures duration in nanoseconds. In the following example,
 a `Timer` metric is used to measure the duration of a method's execution.  Whenever the REST `/cards`
@@ -714,6 +716,84 @@ curl -H "Accept: application/json"  http://localhost:8080/metrics/application
 ----
 <1> The current temperature is returned.  Invoke the `/metrics/application` endpoint again and you should get a different value.
 
+[[simple_timer_metric]]
+==== Simple timer metric
+
+The `SimpleTimer` metric counts invocations and accumulates duration (in seconds). In the following example,
+a `SimpleTimer` metric is used to count and measure the duration of a method's execution. Whenever the REST `/cards`
+endpoint is called, the `SimpleTimer` updates its count and total elapsed time.
+
+[source,java]
+.Update the `GreetingCards` class with the following code:
+----
+package io.helidon.examples.quickstart.se;
+
+import io.helidon.metrics.RegistryFactory;
+import io.helidon.webserver.Routing;
+import io.helidon.webserver.ServerRequest;
+import io.helidon.webserver.ServerResponse;
+import io.helidon.webserver.Service;
+import java.util.Collections;
+import javax.json.Json;
+import javax.json.JsonBuilderFactory;
+import javax.json.JsonObject;
+import org.eclipse.microprofile.metrics.MetricRegistry; // <1>
+import org.eclipse.microprofile.metrics.SimpleTimer;
+
+public class GreetingCards implements Service {
+
+  private static final JsonBuilderFactory JSON = Json.createBuilderFactory(Collections.emptyMap());
+  private final SimpleTimer cardTimer; // <2>
+
+  GreetingCards() {
+    RegistryFactory metricsRegistry = RegistryFactory.getInstance();
+    MetricRegistry appRegistry = metricsRegistry.getRegistry(MetricRegistry.Type.APPLICATION);
+    cardTimer = appRegistry.simpleTimer("cardSimpleTimer"); // <3>
+  }
+
+  @Override
+  public void update(Routing.Rules rules) {
+    rules.get("/", this::getDefaultMessageHandler);
+  }
+
+  private void getDefaultMessageHandler(ServerRequest request, ServerResponse response) {
+    cardTimer.time(() -> sendResponse(response, "Here are some cards ...")); // <4>
+  }
+
+  private void sendResponse(ServerResponse response, String msg) {
+    JsonObject returnObject = JSON.createObjectBuilder().add("message", msg).build();
+    response.send(returnObject);
+  }
+}
+----
+<1> Import metrics classes, particularly the `SimpleTimer` interface for this example.
+<2> Declare a `SimpleTimer` member variable.
+<3> Create and register the `SimpleTimer` metric in the `MetricRegistry`.
+<4> Wrap the business logic in the simple timer's `time` method which updates the count and the total elapsed time.
+
+
+[source,bash]
+.Build and run the application, then invoke the endpoints below:
+----
+curl http://localhost:8080/cards
+curl -H "Accept: application/json"  http://localhost:8080/metrics/application
+----
+
+
+[source,json]
+.JSON response:
+----
+{
+  "cardSimpleTimer":
+    {
+      "count":1, <1>
+      "elapsedTime":0.034274025 <2>
+    }
+}
+----
+<1> How many times the `getDefaultMessageHandler` method ran.
+<2> Cumulative time spent in the `getDefaultMessageHandler` method during its executions.
+
 
 === Integration with Kubernetes and Prometheus
 

examples/microprofile/hello-world-explicit/src/main/resources/META-INF/microprofile-config.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2020 Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2020 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.
@@ -18,3 +18,6 @@ app.name=Hello World Application
 app.uri=https://www.example.com
 
 my.property=propertyValue
+
+# Enable the optional MicroProfile Metrics REST.request metrics
+metrics.rest-request.enabled=true

examples/microprofile/hello-world-implicit/src/main/resources/META-INF/microprofile-config.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2020 Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2020 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.
@@ -22,3 +22,5 @@ app.ints=12,12,32,12,44
 
 server.port=7001
 
+# Enable the optional MicroProfile Metrics REST.request metrics
+metrics.rest-request.enabled=true

examples/quickstarts/helidon-quickstart-mp/src/main/resources/META-INF/microprofile-config.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2018 Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2018, 2020 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.
@@ -20,3 +20,6 @@ app.greeting=Hello
 # Microprofile server properties
 server.port=8080
 server.host=0.0.0.0
+
+# Enable the optional MicroProfile Metrics REST.request metrics
+metrics.rest-request.enabled=true

examples/quickstarts/helidon-quickstart-se/src/main/resources/application.yaml

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2018 Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2018, 2020 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.

examples/quickstarts/helidon-standalone-quickstart-mp/src/main/resources/META-INF/microprofile-config.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2019, 2020 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.
@@ -20,3 +20,6 @@ app.greeting=Hello
 # Microprofile server properties
 server.port=8080
 server.host=0.0.0.0
+
+# Enable the optional MicroProfile Metrics REST.request metrics
+metrics.rest-request.enabled=true