Configure the MetricsFeature through application.properties #1108

quarkiverse · Dec 28, 2023 · d3df010 · d3df010
1 parent eda9fcb
commit d3df010
Show file tree

Hide file tree

Showing 13 changed files with 368 additions and 80 deletions.
diff --git a/docs/modules/ROOT/examples/hc5/application.properties b/docs/modules/ROOT/examples/hc5/application.properties
@@ -1,6 +1,7 @@
 quarkus.cxf.client.myCalculator.wsdl = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService?wsdl
 quarkus.cxf.client.myCalculator.client-endpoint-url = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService
 quarkus.cxf.client.myCalculator.service-interface = org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService
+quarkus.cxf.client.myCalculator.metrics.enabled = false
 
 quarkus.cxf.client.observableCalculator.wsdl = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService?wsdl
 quarkus.cxf.client.observableCalculator.client-endpoint-url = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService

diff --git a/docs/modules/ROOT/examples/metrics/application.properties b/docs/modules/ROOT/examples/metrics/application.properties
@@ -1,15 +1,12 @@
-# tag::metrics-server[]
 quarkus.cxf.path = /soap
 quarkus.cxf.endpoint."/hello".implementor = io.quarkiverse.cxf.metrics.server.it.HelloServiceImpl
-quarkus.cxf.endpoint."/hello".features = io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature
-# end::metrics-server[]
+quarkus.cxf.endpoint."/hello".logging.enabled = true
 
-# tag::metrics-client[]
+%dev.quarkus.cxf.client.hello.wsdl = http://localhost:${quarkus.http.port}/soap/hello?wsdl
+%dev.quarkus.cxf.client.hello.client-endpoint-url = http://localhost:${quarkus.http.port}/soap/hello
 quarkus.cxf.client.hello.wsdl = http://localhost:${quarkus.http.test-port}/soap/hello?wsdl
 quarkus.cxf.client.hello.client-endpoint-url = http://localhost:${quarkus.http.test-port}/soap/hello
 quarkus.cxf.client.hello.service-interface = io.quarkiverse.cxf.metrics.server.it.HelloService
-quarkus.cxf.client.hello.features = io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature
-# end::metrics-client[]
 
 # tag::micrometer-export[]
 quarkus.micrometer.export.json.enabled = true

diff --git a/docs/modules/ROOT/pages/includes/quarkus-cxf-rt-features-metrics.adoc b/docs/modules/ROOT/pages/includes/quarkus-cxf-rt-features-metrics.adoc
@@ -0,0 +1,64 @@
+
+:summaryTableId: quarkus-cxf-rt-features-metrics
+[.configuration-legend]
+icon:lock[title=Fixed at build time] Configuration property fixed at build time - All other configuration properties are overridable at runtime
+[.configuration-reference.searchable, cols="80,.^10,.^10"]
+|===
+
+h|[[quarkus-cxf-rt-features-metrics_configuration]]link:#quarkus-cxf-rt-features-metrics_configuration[Configuration property]
+
+h|Type
+h|Default
+
+a| [[quarkus-cxf-rt-features-metrics_quarkus.cxf.metrics.enabled-for]]`link:#quarkus-cxf-rt-features-metrics_quarkus.cxf.metrics.enabled-for[quarkus.cxf.metrics.enabled-for]`
+
+
+[.description]
+--
+Specifies whether the metrics collection will be enabled for clients, services, both or none. This global setting can be overridden per client or service endpoint using the `quarkus.cxf.client."clients".metrics.enabled` or `quarkus.cxf.endpoint."endpoints".metrics.enabled` option respectively.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_METRICS_ENABLED_FOR+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_METRICS_ENABLED_FOR+++`
+endif::add-copy-button-to-env-var[]
+-- a|
+`clients`, `services`, `both`, `none` 
+|`both`
+
+
+a| [[quarkus-cxf-rt-features-metrics_quarkus.cxf.client.-clients-.metrics.enabled]]`link:#quarkus-cxf-rt-features-metrics_quarkus.cxf.client.-clients-.metrics.enabled[quarkus.cxf.client."clients".metrics.enabled]`
+
+
+[.description]
+--
+If `true` and if `quarkus.cxf.metrics.enabled-for` is set to `both` or `clients` then the `MetricsFeature` will be added to this client; otherwise the feature will not be added to this client.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_CLIENT__CLIENTS__METRICS_ENABLED+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_CLIENT__CLIENTS__METRICS_ENABLED+++`
+endif::add-copy-button-to-env-var[]
+--|boolean 
+|`true`
+
+
+a| [[quarkus-cxf-rt-features-metrics_quarkus.cxf.endpoint.-endpoints-.metrics.enabled]]`link:#quarkus-cxf-rt-features-metrics_quarkus.cxf.endpoint.-endpoints-.metrics.enabled[quarkus.cxf.endpoint."endpoints".metrics.enabled]`
+
+
+[.description]
+--
+If `true` and if `quarkus.cxf.metrics.enabled-for` is set to `both` or `services` then the `MetricsFeature` will be added to this service endpoint; otherwise the feature will not be added to this service endpoint.
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_CXF_ENDPOINT__ENDPOINTS__METRICS_ENABLED+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_CXF_ENDPOINT__ENDPOINTS__METRICS_ENABLED+++`
+endif::add-copy-button-to-env-var[]
+--|boolean 
+|`true`
+
+|===
diff --git a/docs/modules/ROOT/pages/reference/extensions/quarkus-cxf-rt-features-metrics.adoc b/docs/modules/ROOT/pages/reference/extensions/quarkus-cxf-rt-features-metrics.adoc
@@ -15,8 +15,8 @@ endif::[]
 
 Collect metrics using https://micrometer.io/[Micrometer].
 
-NOTE: https://cxf.apache.org/docs/dropwizard-metrics.html[Dropwizard Metrics] are unsupported.
-      They do not work in native mode and the are no tests for JVM mode.
+IMPORTANT: https://cxf.apache.org/docs/dropwizard-metrics.html[Dropwizard Metrics] are not supported.
+           They do not work in native mode and the are no tests for JVM mode.
 
 
 [id="quarkus-cxf-rt-features-metrics-maven-coordinates"]
@@ -41,32 +41,32 @@ endif::[]
 [id="quarkus-cxf-rt-features-metrics-usage"]
 == Usage
 
-The integration of CXF into https://quarkus.io/guides/micrometer[Quarkus Micrometer] ecosystem is implemented using
-https://github.com/apache/cxf/blob/master/rt/features/metrics/src/main/java/org/apache/cxf/metrics/micrometer/MicrometerMetricsProvider.java[CXF MicrometerMetricsProvider]
-and `io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature`.
+The integration of CXF into the https://quarkus.io/guides/micrometer[Quarkus Micrometer] ecosystem is implemented using
+`io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature`.
+As long as your application depends on `quarkus-cxf-rt-features-metrics`,
+an instance of `QuarkusCxfMetricsFeature` is created internally
+and enabled by default for all clients and service endpoints created by {quarkus-cxf-project-name}.
+You can disable it via `quarkus.cxf.metrics.enabled-for`, `quarkus.cxf.client."clients".metrics.enabled`
+and `quarkus.cxf.endpoint."endpoints".metrics.enabled` properties documented below.
 
-NOTE: The sample code snippets used in this section come from the
-     https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/metrics[metrics integration test]
-     in the source tree of {quarkus-cxf-project-name}
+[id="extensions-quarkus-cxf-rt-features-metrics-usage-runnable-example"]
+=== Runnable example
 
-To enable metrics collection for services, just add `io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature`
-to your service's features:
+There is an https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/metrics[integration test]
+covering Micrometer Metrics in the {quarkus-cxf-project-name} source tree.
 
-.application.properties
-[source,properties]
-----
-include::example$metrics/application.properties[tag=metrics-server]
-----
+Unsurprisingly, it depends on `quarkus-cxf-rt-features-metrics`
 
-The same can be done for a client:
-
-.application.properties
-[source,properties]
+.pom.xml
+[source,xml]
 ----
-include::example$metrics/application.properties[tag=metrics-client]
+<dependency>
+    <groupId>io.quarkiverse.cxf</groupId>
+    <artifactId>quarkus-cxf-rt-features-metrics</artifactId>
+</dependency>
 ----
 
-Finally, to export the metrics in json format and for Prometheus, add the following dependency to your project
+It is using `quarkus-micrometer-registry-prometheus` extension to export the metrics in JSON format and for Prometheus:
 
 .pom.xml
 [source,xml]
@@ -77,16 +77,33 @@ Finally, to export the metrics in json format and for Prometheus, add the follow
 </dependency>
 ----
 
-and set the following properties
+The following configuration is needed to be able to inspect the collected metrics over a REST endpoint:
 
 .application.properties
 [source,properties]
 ----
 include::example$metrics/application.properties[tag=micrometer-export]
 ----
 
-After that, you should be able to see some metrics under `cxf.server.requests` and/or `cxf.client.requests` in the output of
-the endpoints you configured above:
+Having all the above in place, you can start the application in Dev mode:
+
+[source,shell]
+----
+$ mvn quarkus:dev
+----
+
+Now send a request to the `HelloService`:
+
+[source,shell]
+----
+$ curl \
+  -d '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:helloResponse xmlns:ns2="http://it.server.metrics.cxf.quarkiverse.io/"><return>Hello Joe!</return></ns2:helloResponse></soap:Body></soap:Envelope>' \
+  -H 'Content-Type: text/xml' \
+  -X POST \
+  http://localhost:8080/metrics/client/hello
+----
+
+After that, you should see some metrics under `cxf.server.requests` in the output of the endpoint you configured above:
 
 [source,shell]
 ----
@@ -98,20 +115,10 @@ metrics: {
         "elapsedTime;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=/soap/hello": 64.0
     },
     ...
-    "cxf.client.requests": {
-        "count;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=http://localhost:808 /soap/hello": 1,
-        "elapsedTime;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=http://localhost:8081/soap/hello": 34.0
-    },
-    ...
 }
 ----
 
 
 [id="quarkus-cxf-rt-features-metrics-configuration"]
 == Configuration
-
-The metrics feature can be associated with a SOAP client or service using the following configuration properties:
-
-* `xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus.cxf.endpoint.-endpoints-.features[quarkus.cxf.endpoint."endpoints".features]`
-* `xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus.cxf.client.-clients-.features[quarkus.cxf.client."clients".features]`
-
+include::../../includes/quarkus-cxf-rt-features-metrics.adoc[]
diff --git a/...yment/src/main/java/io/quarkiverse/cxf/metrics/deployment/QuarkusCxfMetricsProcessor.java b/...yment/src/main/java/io/quarkiverse/cxf/metrics/deployment/QuarkusCxfMetricsProcessor.java
@@ -5,7 +5,9 @@
 import org.apache.cxf.metrics.MetricsFeature;
 import org.apache.cxf.metrics.codahale.CodahaleMetricsProvider;
 
+import io.quarkiverse.cxf.metrics.MetricsCustomizer;
 import io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature;
+import io.quarkus.arc.deployment.AdditionalBeanBuildItem;
 import io.quarkus.deployment.annotations.BuildProducer;
 import io.quarkus.deployment.annotations.BuildStep;
 import io.quarkus.deployment.builditem.FeatureBuildItem;
@@ -40,4 +42,10 @@ void runtimeInitializedClass(BuildProducer<RuntimeInitializedClassBuildItem> run
                  */
                 CodahaleMetricsProvider.class.getName()));
     }
+
+    @BuildStep
+    void additionalBeans(BuildProducer<AdditionalBeanBuildItem> additionalBeans) {
+        additionalBeans.produce(
+                new AdditionalBeanBuildItem(MetricsCustomizer.class));
+    }
 }
diff --git a/extensions/features-metrics/runtime/pom.xml b/extensions/features-metrics/runtime/pom.xml
@@ -81,6 +81,29 @@
                     </annotationProcessorPaths>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-configuration-documentation</id>
+                        <phase>process-classes</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${maven.multiModuleProjectDirectory}/docs/modules/ROOT/pages/includes/</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>${maven.multiModuleProjectDirectory}/target/asciidoc/generated/config/</directory>
+                                    <include>${project.artifactId}.adoc</include>
+                                    <filtering>false</filtering>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 </project>
diff --git a/extensions/features-metrics/runtime/src/main/doc/configuration.adoc b/extensions/features-metrics/runtime/src/main/doc/configuration.adoc
diff --git a/extensions/features-metrics/runtime/src/main/doc/intro.adoc b/extensions/features-metrics/runtime/src/main/doc/intro.adoc
@@ -1,4 +1,4 @@
 Collect metrics using https://micrometer.io/[Micrometer].
 
-NOTE: https://cxf.apache.org/docs/dropwizard-metrics.html[Dropwizard Metrics] are unsupported.
-      They do not work in native mode and the are no tests for JVM mode.
+IMPORTANT: https://cxf.apache.org/docs/dropwizard-metrics.html[Dropwizard Metrics] are not supported.
+           They do not work in native mode and the are no tests for JVM mode.
diff --git a/extensions/features-metrics/runtime/src/main/doc/usage.adoc b/extensions/features-metrics/runtime/src/main/doc/usage.adoc
@@ -1,29 +1,28 @@
-The integration of CXF into https://quarkus.io/guides/micrometer[Quarkus Micrometer] ecosystem is implemented using
-https://github.com/apache/cxf/blob/master/rt/features/metrics/src/main/java/org/apache/cxf/metrics/micrometer/MicrometerMetricsProvider.java[CXF MicrometerMetricsProvider]
-and `io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature`.
+The integration of CXF into the https://quarkus.io/guides/micrometer[Quarkus Micrometer] ecosystem is implemented using
+`io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature`.
+As long as your application depends on `quarkus-cxf-rt-features-metrics`,
+an instance of `QuarkusCxfMetricsFeature` is created internally
+and enabled by default for all clients and service endpoints created by {quarkus-cxf-project-name}.
+You can disable it via `quarkus.cxf.metrics.enabled-for`, `quarkus.cxf.client."clients".metrics.enabled`
+and `quarkus.cxf.endpoint."endpoints".metrics.enabled` properties documented below.
 
-NOTE: The sample code snippets used in this section come from the
-     https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/metrics[metrics integration test]
-     in the source tree of {quarkus-cxf-project-name}
+=== Runnable example
 
-To enable metrics collection for services, just add `io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature`
-to your service's features:
+There is an https://github.com/quarkiverse/quarkus-cxf/tree/main/integration-tests/metrics[integration test]
+covering Micrometer Metrics in the {quarkus-cxf-project-name} source tree.
 
-.application.properties
-[source,properties]
-----
-include::example$metrics/application.properties[tag=metrics-server]
-----
-
-The same can be done for a client:
+Unsurprisingly, it depends on `quarkus-cxf-rt-features-metrics`
 
-.application.properties
-[source,properties]
+.pom.xml
+[source,xml]
 ----
-include::example$metrics/application.properties[tag=metrics-client]
+<dependency>
+    <groupId>io.quarkiverse.cxf</groupId>
+    <artifactId>quarkus-cxf-rt-features-metrics</artifactId>
+</dependency>
 ----
 
-Finally, to export the metrics in json format and for Prometheus, add the following dependency to your project
+It is using `quarkus-micrometer-registry-prometheus` extension to export the metrics in JSON format and for Prometheus:
 
 .pom.xml
 [source,xml]
@@ -34,16 +33,33 @@ Finally, to export the metrics in json format and for Prometheus, add the follow
 </dependency>
 ----
 
-and set the following properties
+The following configuration is needed to be able to inspect the collected metrics over a REST endpoint:
 
 .application.properties
 [source,properties]
 ----
 include::example$metrics/application.properties[tag=micrometer-export]
 ----
 
-After that, you should be able to see some metrics under `cxf.server.requests` and/or `cxf.client.requests` in the output of
-the endpoints you configured above:
+Having all the above in place, you can start the application in Dev mode:
+
+[source,shell]
+----
+$ mvn quarkus:dev
+----
+
+Now send a request to the `HelloService`:
+
+[source,shell]
+----
+$ curl \
+  -d '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:helloResponse xmlns:ns2="http://it.server.metrics.cxf.quarkiverse.io/"><return>Hello Joe!</return></ns2:helloResponse></soap:Body></soap:Envelope>' \
+  -H 'Content-Type: text/xml' \
+  -X POST \
+  http://localhost:8080/metrics/client/hello
+----
+
+After that, you should see some metrics under `cxf.server.requests` in the output of the endpoint you configured above:
 
 [source,shell]
 ----
@@ -55,10 +71,5 @@ metrics: {
         "elapsedTime;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=/soap/hello": 64.0
     },
     ...
-    "cxf.client.requests": {
-        "count;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=http://localhost:808 /soap/hello": 1,
-        "elapsedTime;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=http://localhost:8081/soap/hello": 34.0
-    },
-    ...
 }
 ----