From f75b6e902bd119f7c4d02fb3cbba4f731b52f71e Mon Sep 17 00:00:00 2001 From: Ken Finnigan Date: Wed, 2 Jun 2021 14:35:35 -0400 Subject: [PATCH] Add Guide for OpenTelemetry Resolves #16093 --- docs/src/main/asciidoc/opentelemetry.adoc | 182 ++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 docs/src/main/asciidoc/opentelemetry.adoc diff --git a/docs/src/main/asciidoc/opentelemetry.adoc b/docs/src/main/asciidoc/opentelemetry.adoc new file mode 100644 index 0000000000000..83c7e7e3aa626 --- /dev/null +++ b/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] +---- + + io.quarkus + quarkus-opentelemetry-exporter-jaeger + +---- + +=== 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]