[WFLY-15849] OpenTelemetry Quickstart

.github/workflows/quickstart_opentelemetry_ci.yml

@@ -0,0 +1,15 @@
+
+name: WildFly OpenTelemetry 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: opentelemetry-tracing
+      MICROPROFILE: false

opentelemetry-tracing/README.adoc

@@ -0,0 +1,157 @@
+include::../shared-doc/attributes.adoc[]
+
+= observability-tracing: OpenTelemetry Tracing QuickStart
+:author: Jason Lee
+:level: Beginner
+:technologies: OpenTelemetry Tracing
+:custom-bootable-jar-layers: {lt}layer{gt}opentelemetry{lt}/layer{gt}
+
+[abstract]
+The `observability-tracing` quickstart demonstrates the use of the OpenTelemetry tracing specification in {productName}.
+
+:standalone-server-type: default
+:archiveType: war
+:archiveName: {artifactId}
+:restoreScriptName: restore-configuration.cli
+
+
+== What is it?
+
+OpenTelemetry is a set of APIs, SDKs, tooling and integrations that are designed for the creation and management of
+telemetry data such as traces, metrics, and logs. OpenTelemetry support in {productName} is limited to traces only.
+{productName}'s support of OpenTelemetry provides out of the box tracing of Jakarta REST calls, as well as
+container-managed Jakarta REST Client invocations. Additionally, applications can have injected a `Tracer` instance
+in order to create and manage custom `Span`s as a given application may require. By default, these traces are exported
+to a Jaeger instance listening on the same host.
+
+== Architecture
+
+In this quickstart, we have a collection of CDI beans and REST endpoints that  expose functionalities of the OpenTelemetry support in {productName}.
+
+// System Requirements
+include::../shared-doc/system-requirements.adoc[leveloffset=+1]
+
+// Use of {jbossHomeName}
+include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
+
+== Steps
+
+[[configure_the_server]]
+=== Configure the Server
+
+You enable Micrometer by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-micrometer.cli` script provided in the root directory of this quickstart.
+
+. Before you begin, make sure you do the following:
+
+* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above.
+* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above.
+
+. Review the `configure-micrometer.cli` file in the root of this quickstart directory. This script adds the configuration that enables Micrometer for the quickstart components. Comments in the script describe the purpose of each block of commands.
+. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}__` with the path to your server:
++
+[source,subs="+quotes,attributes+",options="nowrap"]
+----
+$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-opentelemetry.cli
+----
++
+NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script.
++
+
+You should see the following result when you run the script:
++
+[source,options="nowrap"]
+----
+The batch executed successfully
+process-state: reload-required
+----
+
+. You'll need to reload the configuration after that:
++
+[source,subs="+quotes,attributes+",options="nowrap"]
+----
+$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --commands=reload
+----
+
+== Running the Jaeger service
+
+To collect the traces from our application we will be using the Jaeger tracing system. To run the Jaeger service we will use its Docker container.
+
+Run the following command, or execute `jaeger.sh` in the project directory:
+
+[source,bash]
+----
+include::jaeger.sh[]
+----
+
+NOTE: If this is your first time running Jaeger in this manner, this can take a minute.
+
+Now you can access `http://localhost:16686` in your browser to see the Jaeger UI console.
+
+Now we can start adding our custom spans from our application.
+
+=== Creating traces
+
+==== Implicit tracing of REST resources
+
+The OpenTelemetry support in {productName} provides an implicit tracing of all Jakarta REST resources. That means that for all applications, {productName} will automatically:
+
+* extract the Span context from the incoming Jakarta REST request
+* start a new Span on incoming Jakarta REST request and close it when the request is completed
+* inject Span context to any outgoing Jakarta REST request
+* start a Span for any outgoing Jakarta REST request and finish the Span when the request is completed
+
+==== Explicit tracing
+
+The OpenTelemetry API also supports explicit tracing should your application required it:
+
+[source,java]
+-----
+include::src/main/java/org/wildfly/quickstarts/opentelemetry/ExplicitlyTracedBean.java[]
+-----
+
+include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]
+
+== Access the quickstart application
+
+You can either access the application via your browser at http://localhost:8080/opentelemetry-tracing/hello/implicit-trace[], or http://localhost:8080/opentelemetry-tracing/hello/explicit-trace[]. You can also access it from the command line:
+
+[source,bash]
+----
+$ curl http://localhost:8080/opentelemetry-tracing/hello/implicit-trace
+$ curl http://localhost:8080/opentelemetry-tracing/hello/explicit-trace
+----
+
+Either endpoing should return a simple document:
+
+[source]
+-----
+hello
+-----
+
+=== View the traces
+
+You can view the traces by accessing the Jaeger http://localhost:16686/[console].
+
+// Server Distribution Testing
+include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2]
+// Undeploy the Quickstart
+include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2]
+//  Restore the {productName} Standalone Server Configuration
+include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2]
+// Restore the {productName} Standalone Server Configuration Manually
+include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3]
+// 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
+
+OpenTelemetry Tracing provides the mechanisms for your application to participate
+in the distributed tracing with minimal effort on the application side. The Jakarta REST
+resources are always traced by default, but the specification allows you to create
+individual spans directly with the CDI injection of the `io.opentelemetry.api.trace.Tracer`.

opentelemetry-tracing/charts/helm.yaml

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

opentelemetry-tracing/configure-opentelemetry.cli

@@ -0,0 +1,6 @@
+# CLI script to enable OpenTelemetry for the quickstart application in the application server
+/extension=org.wildfly.extension.opentelemetry:add()
+/subsystem=opentelemetry:add()
+
+# Reload the server configuration
+reload

opentelemetry-tracing/jaeger.sh

@@ -0,0 +1,11 @@
+docker run \
+    -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
+    -p 5775:5775/udp \
+    -p 6831:6831/udp \
+    -p 6832:6832/udp \
+    -p 5778:5778 \
+    -p 16686:16686 \
+    -p 14268:14268 \
+    -p 14250:14250 \
+    -p 9411:9411 \
+    jaegertracing/all-in-one:latest