Improve doc of auto and paths

Author: tjquinno

docs/src/main/asciidoc/includes/metrics/metrics-config.adoc

@@ -91,22 +91,50 @@ endif::se-flavor[]
 ==== Selecting REST Endpoints for Automatic Measurement
 You can choose which endpoints to include in Helidon's automatic measurements using the `auto` config section.
 
-If you omit the `auto` section, Helidon measures all endpoints.
+include::{rootdir}/config/io_helidon_webserver_observe_metrics_AutoHttpMetricsConfig.adoc[tag=config,leveloffset=+2]
 
-If you specify the `auto` section, by default Helidon does not measure built-in endpoints such as metrics, health, and openapi. You can add items under  `auto.paths` to control more exactly which endpoints to measure.
+The `paths` section contains zero or more entries, each entry having the following settings:
 
-If you include the  `paths` section, a given request matches an entry if its path matches the path pattern and its HTTP method is in the `methods` list. If there is no `methods` list for an entry, all HTTP methods match the entry.
+--
+.`path` entry settings
+[cols="4,2,4,20"]
+|====
+|Key | Required | Default Value | Usage
+
+| `path`
+| yes
+| {nbsp}
+a| Path-matching expression:
+
+* an exact match (`/greet`)
+* a prefix match (`/greet/*`)
+* a pattern match (`/greet/{name}`)
+
+| `methods` | {nbsp} | all HTTP method types | Which HTTP methods match this entry
 
-If a request matches an entry, the request is measured if the entry's `enabled` setting is true (the default).
+| `enabled` | {nbsp} | `true` | Whether this entry votes to match requests which match the entry
+|====
+--
 
-If a request matches multiple entries, the last one matched wins.
+Helidon decides whether to measure incoming requests as follows:
 
-If a request matches no entries, it is measured.
+* If you omit the `auto` configuration, Helidon measures all endpoints.
+* If you specify the `auto` configuration, by default Helidon does not measure built-in endpoints such as metrics, health, and openapi. You can add items under  `auto.paths` to control more exactly which endpoints to measure.
+* If you include the  `paths` section, Helidon checks a request against the path entries in order. A given request matches an entry if its path matches the path pattern and its HTTP method is in the `methods` list. If there is no `methods` list for an entry, all HTTP methods match the entry.
+* If a request matches an entry, the entry "votes" whether the request should be measured based on the entry's `enabled` setting.
+* If a request matches multiple entries, the last one voting wins.
+* If a request matches no entries, it is measured.
 
-You can also control which sockets are included in the measurements.
+The `auto.sockets` setting controls which sockets are included in the measurements; if not set, Helidon measures requests on all sockets.
 
+ifdef::se-flavor[]
 [source,yaml]
+endif::se-flavor[]
+ifdef::mp-flavor[]
+[source,properties]
+endif::mp-flavor[]
 .Including and Excluding Endpoints from Automatic Measurement
+ifdef::se-flavor[]
 ----
 server:
   features:
@@ -121,6 +149,18 @@ server:
                 enabled: false
             sockets: ["@default","private"] # <3>
 ----
+endif::se-flavor[]
+ifdef::mp-flavor[]
+----
+server.features.observe.observers.metrics.auto.paths.0.path=/greet        # <1>
+server.features.observe.observers.metrics.auto.paths.0.methods=GET,HEAD
+
+server.features.observe.observers.metrics.auto.paths.1.path=/greet/{name} # <2>
+server.features.observe.observers.metrics.auto.paths.1.enabled=false
+
+server.features.observe.observers.metrics.auto.sockets=@default,private   # <3>
+----
+endif::mp-flavor[]
 <1> Measure `/greet` for only `GET` and `HEAD` requests.
 <2> Do not measure the personalized greeting requests.
 <3> Measure only endpoints on the default socket and the socket named `private`. Endpoints on other sockets (such as if you had an `admin` socket) are not measured.

microprofile/metrics/src/test/java/io/helidon/microprofile/metrics/HelloWorldPathMethodSelectionTest.java

@@ -59,16 +59,13 @@
  */
 @HelidonTest
 @AddConfig(key = "metrics." + MetricsCdiExtension.REST_ENDPOINTS_METRIC_ENABLED_PROPERTY_NAME, value = "true")
-@AddConfig(key = "metrics.permit-all", value = "true")
-@AddConfigBlock(type = "yaml", value = """
-                metrics:
-                  auto:
-                    paths:
-                      - path: "/"
-                        methods: ["HEAD"]
-                      - path: "/withArg/{name}"
-                        enabled: false
+@AddConfigBlock(value = """
+        metrics.auto.paths.0.path=/
+        metrics.auto.paths.0.methods=HEAD,OPTIONS
+        metrics.auto.paths.1.path=/withArg/{name}
+        metrics.auto.paths.1.enabled=false
         """)
+
 @AddBean(CatchAllExceptionMapper.class)
 class HelloWorldPathMethodSelectionTest {
 

webserver/observe/metrics/src/main/java/io/helidon/webserver/observe/metrics/AutoHttpMetricsConfigBlueprint.java

@@ -49,6 +49,11 @@ interface AutoHttpMetricsConfigBlueprint {
 
     /**
      * Automatic metrics collection settings. Default excludes built-in Helidon paths (e.g., metrics, health).
+     * A request's path and HTTP method are checked against each entry under {@code paths} in order.
+     * <ul>
+     *     <li>If a request matches no entry, then the request is measured.</li>
+     *     <li>If a request matches multiple entries, then the last match wins.</li>
+     * </ul>
      *
      * @return automatic metrics collection settings
      */

webserver/observe/metrics/src/main/java/io/helidon/webserver/observe/metrics/AutoHttpMetricsPathConfigBlueprint.java

@@ -28,8 +28,11 @@
 /**
  * Settings for path-based automatic metrics configuration.
  * <p>
- * The {@link #enabled} setting (true or false) applies to any request which matches the {@linkplain #path() path matcher} and the
- * {@linkplain #methods() HTTP methods} specified.
+ * An HTTP request matches a path entry if the request path matches the entry's path pattern and the request's HTTP method
+ * matches one of the entry's methods. If there no {@code methods} list for the entry, then all HTTP methods match the entry.
+ * <p>
+ * If a request matches an entry, then the entry's {@code enabled} value (which defaults to {@code}) determines the entry's vote
+ * whether the request should be measured. If a request matches multiple entries, the vote of the last matched entry wins.
  *
  */
 @Prototype.Configured
@@ -51,7 +54,8 @@ static AutoHttpMetricsPathConfig disabled(String path) {
     }
 
     /**
-     * Whether automatic metrics are to be enabled for the specified {@link io.helidon.http.PathMatcher} and HTTP methods.
+     * Whether automatic metrics are to be enabled for requests which match the specified {@link io.helidon.http.PathMatcher}
+     * and HTTP methods.
      *
      * @return whether auto metrics are to be enabled for this path config's path matcher and HTTP methods
      */
@@ -68,7 +72,7 @@ static AutoHttpMetricsPathConfig disabled(String path) {
     PathMatcher path();
 
     /**
-     * HTTP methods for which this path config applies.
+     * HTTP methods for which this path config applies; default is to match all HTTP methods.
      *
      * @return HTTP methods
      */