Add Guide for OpenTelemetry

Resolves #16093

docs/src/main/asciidoc/opentelemetry.adoc

@@ -0,0 +1,182 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= Quarkus - Using OpenTelemetry
+
+include::./attributes.adoc[]
+
+This guide explains how your Quarkus application can utilize https://opentelemetry.io/[OpenTelemetry] to provide
+distributed tracing for interactive web applications.
+
+== Prerequisites
+
+To complete this guide, you need:
+
+* less than 15 minutes
+* an IDE
+* JDK 11+ installed with `JAVA_HOME` configured appropriately
+* Apache Maven {maven-version}
+* Docker
+
+
+
+== Architecture
+
+In this guide, we create a straightforward REST application to demonstrate distributed tracing.
+
+== Solution
+
+We recommend that you follow the instructions in the next sections and create the application step by step.
+However, you can skip right to the completed example.
+
+Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].
+
+The solution is located in the `opentelemetry-quickstart` {quickstarts-tree-url}/opentelemetry-quickstart[directory].
+
+== Creating the Maven project
+
+First, we need a new project. Create a new project with the following command:
+
+[source,bash,subs=attributes+]
+----
+mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \
+    -DprojectGroupId=org.acme \
+    -DprojectArtifactId=opentelemetry-quickstart \
+    -DclassName="org.acme.opentelemetry.TracedResource" \
+    -Dpath="/hello" \
+    -Dextensions="resteasy,quarkus-opentelemetry-exporter-jaeger"
+cd opentelemetry-quickstart
+----
+
+This command generates the Maven project with a REST endpoint and imports the `quarkus-opentelemetry-exporter-jaeger` extension,
+which includes the OpenTelemetry support,
+and a gRPC span exporter for https://www.jaegertracing.io/[Jaeger].
+
+If you already have your Quarkus project configured, you can add the `quarkus-opentelemetry-exporter-jaeger` extension
+to your project by running the following command in your project base directory:
+
+[source,bash]
+----
+./mvnw quarkus:add-extension -Dextensions="opentelemetry-jaeger-exporter"
+----
+
+This will add the following to your `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-opentelemetry-exporter-jaeger</artifactId>
+</dependency>
+----
+
+=== Examine the JAX-RS resource
+
+Open the `src/main/java/org/acme/opentelemetry/TracedResource.java` file and see the following content:
+
+[source,java]
+----
+package org.acme.opentelemetry;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import org.jboss.logging.Logger;
+
+@Path("/hello")
+public class TracedResource {
+
+    private static final Logger LOG = Logger.getLogger(TracedResource.class);
+
+    @GET
+    @Produces(MediaType.TEXT_PLAIN)
+    public String hello() {
+        LOG.info("hello");
+        return "hello";
+    }
+}
+----
+
+Notice that there is no tracing specific code included in the application. By default, requests sent to this
+endpoint will be traced without any required code changes.
+
+=== Create the configuration
+
+There are two ways to configure the Jaeger gRPC Exporter within the application.
+
+The first approach is by providing the properties within the `src/main/resources/application.properties` file:
+
+[source,properties]
+----
+quarkus.application.name=myservice // <1>
+quarkus.opentelemetry.enabled=true // <2>
+quarkus.opentelemetry.tracer.exporter.jaeger.endpoint=http://localhost:14250 // <3>
+----
+
+<1> All spans created from the application will include an OpenTelemetry `Resource` indicating the span was created by the `myservice` application. If not set, it will default to the artifact id.
+<2> Whether OpenTelemetry is enabled or not. The default is `true`, but shown here to indicate how it can be disabled
+<3> gRPC endpoint for sending spans.
+
+== Run the application
+
+The first step is to start the https://www.jaegertracing.io/[Jaeger] "all in one" to collect and display the captured traces:
+
+[source,bash]
+----
+docker run -p 5775:5775/udp -p 6831:6831/udp -p 6832:6832/udp -p 5778:5778 -p 16686:16686 -p 14250:14250 jaegertracing/all-in-one:latest
+----
+
+Now we are ready to run our application. If using `application.properties` to configure the tracer:
+
+[source,bash]
+----
+./mvnw compile quarkus:dev
+----
+
+or if configuring the Jaeger gRPC endpoint via environment variables:
+
+[source,bash]
+----
+./mvnw compile quarkus:dev -Djvm.args="-DQUARKUS_OPENTELEMETRY_TRACER_EXPORTER_JAEGER_ENDPOINT=http://localhost:14250"
+----
+
+With the Jaeger system and application running, you can make a request to the provided endpoint:
+
+[source,shell]
+----
+$ curl http://localhost:8080/hello
+hello
+----
+
+Then visit the http://localhost:16686[Jaeger UI] to see the tracing information.
+
+Hit `CTRL+C` to stop the application.
+
+== Additional instrumentation
+
+Some Quarkus extensions will require additional code to ensure traces are propagated to subsequent execution.
+These sections will outline what is necessary to propagate traces across process boundaries.
+
+The instrumentation documented in this section has been tested with Quarkus and works in both standard and native mode.
+
+=== SmallRye Reactive Messaging - Kafka
+
+When using the SmallRye Reactive Messaging extension for Kafka,
+we are able to propagate the span into the Kafka Record with:
+
+[source,java]
+----
+Metadata.of(TracingMetadata.withPrevious(Context.current()));
+----
+
+The above creates a `Metadata` object we can add to the `Message` being produced,
+which retrieves the OpenTelemetry `Context` to extract the current span for propagation.
+
+[[configuration-reference]]
+== OpenTelemetry Configuration Reference
+
+include::{generated-dir}/config/quarkus-opentelemetry.adoc[leveloffset=+1, opts=optional]
+include::{generated-dir}/config/quarkus-opentelemetry-exporter-jaeger.adoc[leveloffset=+1, opts=optional]