[WFLY-17678] Add Micrometer quickstart

Add module
Develop demo app
Document QS

.github/workflows/quickstart_micrometer_ci.yml

@@ -0,0 +1,14 @@
+name: WildFly Micrometer Quickstart CI
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'micrometer/**'
+      - '.github/workflows/quickstart_ci.yml'
+jobs:
+  call-quickstart_ci:
+    uses: ./.github/workflows/quickstart_ci.yml
+    with:
+      QUICKSTART_PATH: micrometer
+      MICROPROFILE: false

README.adoc

@@ -177,6 +177,7 @@ NOTE: Some of these quickstarts use the H2 database included with {productNameFu
 | link:logging/README{outfilesuffix}[logging]|Logging | The `logging` quickstart demonstrates how to configure different logging levels in {productName}. It also includes an asynchronous logging example. | Intermediate | _none_
 | link:mail/README{outfilesuffix}[mail]|JavaMail, CDI, JSF | The `mail` quickstart demonstrates how to send email using CDI and JSF and the default Mail provider that ships with {productName}. | Beginner | _none_
 | link:messaging-clustering-singleton/README{outfilesuffix}[messaging-clustering-singleton]|JMS, MDB, Clustering | The `messaging-clustering-singleton` quickstart uses a JMS topic and a queue to demonstrate clustering using {productName} messaging with MDB singleton configuration where only one node in the cluster will be active. | Advanced | _none_
+| link:micrometer/README{outfilesuffix}[micrometer]|Micrometer | The `micrometer` quickstart demonstrates the use of the Micrometer library in {productName}. | Beginner | _none_
 | link:microprofile-config/README{outfilesuffix}[microprofile-config]|MicroProfile Config | The `microprofile-config` quickstart demonstrates the use of the MicroProfile Config specification in {productName}. | Beginner | _none_
 | link:microprofile-fault-tolerance/README{outfilesuffix}[microprofile-fault-tolerance]|MicroProfile, Fault Tolerance | The `microprofile-fault-tolerance` quickstart demonstrates how to use Eclipse MicroProfile Fault Tolerance in {productName}. | Intermediate | _none_
 | link:microprofile-health/README{outfilesuffix}[microprofile-health]|MicroProfile Health | The `microprofile-health` quickstart demonstrates the use of the MicroProfile Health specification in {productName}. | Beginner | _none_

micrometer/README.adoc

@@ -0,0 +1,248 @@
+include::../shared-doc/attributes.adoc[]
+
+= micrometer: Micrometer QuickStart
+:author: Jason Lee
+:level: Beginner
+:technologies: Micrometer
+:custom-bootable-jar-layers: {lt}layer{gt}micrometer{lt}/layer{gt}
+
+[abstract]
+The `micrometer` quickstart demonstrates the use of the Micrometer library in {productName}.
+
+:standalone-server-type: default
+:archiveType: jar
+:archiveName: {artifactId}
+
+== What is it?
+
+https://micrometer.io[Micrometer] is a vendor-neutral facade that allows application developers to collect and report application and system metrics to the backend of their choice in an entirely portable manner. By simply replacing the `MeterRegistry` used, or combining them in Micrometer's `CompositeRegistry` data can be exported a variety of monitoring systems with no application code changes.
+
+== Architecture
+
+In this quickstart, we will build a small, simple application that shows the usage of a number of Micrometer's `Meter` implementations. We will also demonstrate the means by which {productName} exports the metrics data, which is via the https://opentelemetry.io/docs/reference/specification/protocol/otlp/[OpenTelemetry Protocol (OTLP)] to the https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]. To provide simpler access to the published metrics, the Collector will be configured with a Prometheus endpoint, from which we can scrape data.
+
+== Prerequisites
+
+To complete this guide, you will need:
+
+* less than 15 minutes
+* JDK 11+ installed with `JAVA_HOME` configured appropriately
+* Apache Maven 3.5.3+
+
+include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
+
+== Steps
+
+include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]
+
+include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]
+
+=== Access the quickstart application
+
+Run following command in your terminal:
+
+[source, shell]
+----
+$ curl http://localhost:8080/micrometer/prime/13
+----
+
+It should return a simple document:
+
+[source]
+-----
+13 is prime.
+-----
+
+
+=== Registering metrics
+
+Micrometer uses a programmatic approach to metrics definition, as opposed the more declarative, annotation-based approach of other libraries. Because of that, we need to explicitly register our `Meter` s before they can be used:
+
+[source,java]
+----
+@Path("/")
+@ApplicationScoped
+public class RootResource {
+    // ...
+    @Inject
+    private MeterRegistry registry;
+
+    private Counter performCheckCounter;
+    private Counter originalCounter;
+    private Counter duplicatedCounter;
+
+    @PostConstruct
+    private void createMeters() {
+        Gauge.builder("prime.highestSoFar", () -> highestPrimeNumberSoFar)
+                .description("Highest prime number so far.")
+                .register(registry);
+        performCheckCounter = Counter
+                .builder("prime.performedChecks")
+                .description("How many prime checks have been performed.")
+                .register(registry);
+        originalCounter = Counter
+                .builder("prime.duplicatedCounter")
+                .tags(List.of(Tag.of("type", "original")))
+                .register(registry);
+        duplicatedCounter = Counter
+                .builder("prime.duplicatedCounter")
+                .tags(List.of(Tag.of("type", "copy")))
+                .register(registry);
+    }
+    // ...
+}
+----
+
+Notice that we start by `@Inject` ing the `MeterRegistry`. This is a {productName}-managed instance, so all applications need to do it inject it and start using. Once we have that, we can use to build and register our meters, which we do in `@PostConstuct private void createMeters()`
+
+[NOTE]
+====
+This must be done _post_-construction, as the `MeterRegistry` must be injected before it can be used to register the meters.
+====
+
+In this example, we register several different types to demonstrate their use. With those registered, we can start writing application logic:
+
+[source,java]
+----
+@GET
+@Path("/prime/{number}")
+public String checkIfPrime(@PathParam("number") long number) throws Exception {
+    performCheckCounter.increment();
+
+    Timer timer = registry.timer("prime.timer");
+
+    return timer.recordCallable(() -> {
+
+        if (number < 1) {
+            return "Only natural numbers can be prime numbers.";
+        }
+
+        if (number == 1) {
+            return "1 is not prime.";
+        }
+
+        if (number == 2) {
+            return "2 is prime.";
+        }
+
+        if (number % 2 == 0) {
+            return number + " is not prime, it is divisible by 2.";
+        }
+
+        for (int i = 3; i < Math.floor(Math.sqrt(number)) + 1; i = i + 2) {
+            try {
+                Thread.sleep(10);
+            } catch (InterruptedException e) {
+                //
+            }
+            if (number % i == 0) {
+                return number + " is not prime, is divisible by " + i + ".";
+            }
+        }
+
+        if (number > highestPrimeNumberSoFar) {
+            highestPrimeNumberSoFar = number;
+        }
+
+        return number + " is prime.";
+    });
+}
+----
+
+This method represents a simple REST endpoint that is able to determine whether the number passed as a path parameter is a prime number.
+
+=== Configuring the server with Micrometer support
+
+Before we can deploy the application to {productName}, however, we need to configure the server. Given that not all environment may want metrics, the Micrometer extension is not enabled by default, so we need to do that now. We can do that by using the command line management too?:
+
+[source,subs="attributes+"]
+----
+$ /path/to/{productName}/bin/jboss-cli.sh -c
+[standalone@localhost:9990 /] /extension=org.wildfly.extension.micrometer:add
+[standalone@localhost:9990 /] /subsystem=micrometer:add(endpoint="http://localhost:4318/v1/metrics")
+[standalone@localhost:9990 /] reload
+----
+
+=== Starting the OpenTelemetry Collector
+
+By default, {productName} will publish metrics every 10 seconds, so you will soon start seeing errors about a refused connection. This is because we told {productName} to publish to a server that is not there, so we need to fix that. To make that as simple as possible, you can use Docker Compose to start an instance of the OpenTelemetry Collector:
+
+[source,yaml]
+----
+include::docker-compose.yml[]
+----
+
+We also need to provide a configuration file for the collector:
+
+[source,yaml]
+----
+include::otel-collector-config.yml[]
+----
+
+We can now bring up the collector instance:
+
+[source,bash]
+----
+$ docker-compose up
+----
+
+The service should be available almost immediately, which you can verify by looking at the Prometheus endpoint we've configured by pointing your browser at http://localhost:1234/metrics[]. You should see quite a few metrics listed, none of which are what our application has registered. What you're seeing are the system and JVM metrics automatically registered and published by {productName} to give systems/applications administrators a comprehensive view of system health and performance.
+
+Now, we're ready to deploy our application:
+
+[source,options="nowrap"]
+----
+$ mvn clean package wildfly:deploy
+----
+
+You can either access the application via your browser at http://localhost:8080/micrometer/prime/13[], or from the command line:
+
+[source,bash]
+----
+$ curl http://localhost:8080/micrometer/prime/13
+----
+
+Once given enough time to allow {productName} to publish metrics updates, you now see your application's meters reported in the http://localhost:1234/metrics[Prometheus export]. You can also view them via the command-line:
+
+[source,bash]
+----
+$ curl -s http://localhost:1234/metrics | grep "prime_"
+# HELP prime_duplicatedCounter
+# TYPE prime_duplicatedCounter counter
+prime_duplicatedCounter{job="wildfly",type="copy"} 0
+prime_duplicatedCounter{job="wildfly",type="original"} 0
+# HELP prime_highestSoFar Highest prime number so far.
+# TYPE prime_highestSoFar gauge
+prime_highestSoFar{job="wildfly"} 13
+# HELP prime_performedChecks How many prime checks have been performed.
+# TYPE prime_performedChecks counter
+prime_performedChecks{job="wildfly"} 1
+# HELP prime_timer
+# TYPE prime_timer histogram
+prime_timer_bucket{job="wildfly",le="+Inf"} 1
+prime_timer_sum{job="wildfly"} 10.941035
+prime_timer_count{job="wildfly"} 1
+
+----
+
+Notice that all four meters registered in the `@PostConstruct` method as well as the `Timer` in our endpoint method have all been published.
+
+// Server Distribution Testing
+include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2]
+
+include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]
+
+// Bootable JAR
+include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1]
+
+// OpenShift
+include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1]
+
+// Build and run sections for other environments/builds
+ifndef::ProductRelease,EAPXPRelease[]
+include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1]
+endif::[]
+
+== Conclusion
+
+Micrometer provides a de facto standard way of capturing and publishing metrics to the monitoring solution of your choice. {productName} provides a convenient, out-of-the-box integration of Micrometer to make it easier to capture those metrics and monitor your application's health and performance. For more information on Micrometer, please refer to the project's https://micrometer.io[website].

micrometer/charts/helm.yaml

@@ -0,0 +1,6 @@
+build:
+  uri: https://github.com/wildfly/quickstart.git
+  ref: main
+  contextDir: micrometer
+deploy:
+  replicas: 1

micrometer/docker-compose.yml

@@ -0,0 +1,17 @@
+version: "3"
+
+services:
+  otel-collector:
+    image: otel/opentelemetry-collector
+    command: [--config=/etc/otel-collector-config.yml]
+    volumes:
+      - ./otel-collector-config.yml:/etc/otel-collector-config.yml
+    ports:
+      - 1888:1888 # pprof extension
+      - 8888:8888 # Prometheus metrics exposed by the collector
+      - 8889:8889 # Prometheus exporter metrics
+      - 13133:13133 # health_check extension
+      - 4317:4317 # OTLP gRPC receiver
+      - 4318:4318 # OTLP http receiver
+      - 55679:55679 # zpages extension
+      - 1234:1234 # /metrics endpoint

micrometer/otel-collector-config.yml

@@ -0,0 +1,29 @@
+extensions:
+  health_check:
+  pprof:
+    endpoint: 0.0.0.0:1777
+  zpages:
+    endpoint: 0.0.0.0:55679
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+      http:
+
+processors:
+  batch:
+
+exporters:
+  prometheus:
+    endpoint: "0.0.0.0:1234"
+
+service:
+  pipelines:
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [prometheus]
+
+  extensions: [health_check, pprof, zpages]
+