////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////
= Quarkus - Using OpenTracing

include::./attributes.adoc[]

This guide explains how your Quarkus application can utilize OpenTracing to provide distributed tracing for
interactive web applications.

== Prerequisites

To complete this guide, you need:

* less than 15 minutes
* an IDE
* JDK 1.8+ 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 `opentracing-quickstart` {quickstarts-tree-url}/opentracing-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=opentracing-quickstart \
    -DclassName="org.acme.opentracing.TracedResource" \
    -Dpath="/hello" \
    -Dextensions="resteasy,quarkus-smallrye-opentracing"
cd opentracing-quickstart
----

This command generates the Maven project with a REST endpoint and imports the `smallrye-opentracing` extension, which
includes the OpenTracing support and the default https://www.jaegertracing.io/[Jaeger] tracer.

If you already have your Quarkus project configured, you can add the `smallrye-opentracing` extension
to your project by running the following command in your project base directory:

[source,bash]
----
./mvnw quarkus:add-extension -Dextensions="smallrye-opentracing"
----

This will add the following to your `pom.xml`:

[source,xml]
----
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-opentracing</artifactId>
</dependency>
----

=== Examine the JAX-RS resource

Open the `src/main/java/org/acme/opentracing/TracedResource.java` file and see the following content:

[source,java]
----
package org.acme.opentracing;

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 code changes being required. It is also possible to enhance the tracing information. For more information on this, please see the https://github.com/eclipse/microprofile-opentracing/blob/master/spec/src/main/asciidoc/microprofile-opentracing.asciidoc[MicroProfile OpenTracing specification].

=== Create the configuration

There are two ways to configure the Jaeger tracer within the application.

The first approach is by providing the properties within the `src/main/resources/application.properties` file:

[source,properties]
----
quarkus.jaeger.service-name=myservice // <1>
quarkus.jaeger.sampler-type=const // <2>
quarkus.jaeger.sampler-param=1 // <3>
quarkus.log.console.format=%d{HH:mm:ss} %-5p traceId=%X{traceId}, parentId=%X{parentId}, spanId=%X{spanId}, sampled=%X{sampled} [%c{2.}] (%t) %s%e%n // <4>
----

<1> If the `quarkus.jaeger.service-name` property (or `JAEGER_SERVICE_NAME` environment variable) is not provided then a "no-op" tracer will be configured, resulting in no tracing data being reported to the backend.
<2> Setup a sampler, that uses a constant sampling strategy.
<3> Sample all requests. Set sampler-param to somewhere between 0 and 1, e.g. 0.50, if you do not wish to sample all requests.
<4> Add trace IDs into log message.

The second approach is to supply the properties as https://www.jaegertracing.io/docs/latest/client-features/[environment variables]. These can be specified as `jvm.args` as shown in the following section.

== Run the application

The first step is to start the tracing system 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 14268:14268 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 tracer via environment variables:

[source,bash]
----
./mvnw compile quarkus:dev -Djvm.args="-DJAEGER_SERVICE_NAME=myservice -DJAEGER_SAMPLER_TYPE=const -DJAEGER_SAMPLER_PARAM=1"
----

Once both the application and tracing system are started, you can make a request to the provided endpoint:

[source,shell]
----
$ curl http://localhost:8080/hello
hello
----
When the first request has been submitted, the Jaeger tracer within the app will be initialized:

[source]
----
2019-10-16 09:35:23,464 INFO  [io.jae.Configuration] (executor-thread-1) Initialized tracer=JaegerTracer(version=Java-0.34.0, serviceName=myservice, reporter=RemoteReporter(sender=UdpSender(), closeEnqueueTimeout=1000), sampler=ConstSampler(decision=true, tags={sampler.type=const, sampler.param=true}), tags={hostname=localhost.localdomain, jaeger.version=Java-0.34.0, ip=127.0.0.1}, zipkinSharedRpcSpan=false, expandExceptionLogs=false, useTraceId128Bit=false)
13:20:11 INFO  traceId=1336b2b0a76a96a3, parentId=0, spanId=1336b2b0a76a96a3, sampled=true [or.ac.qu.TracedResource] (executor-thread-63) hello
----

Then visit the http://localhost:16686[Jaeger UI] to see the tracing information.

Hit `CTRL+C` to stop the application.

== Tracing additional methods

REST endpoints are automatically traced.
If you need to trace additional methods, you can use the `org.eclipse.microprofile.opentracing.Traced` annotation at class or method level.

This can be useful to trace incoming requests from non-REST calls (like request coming from a message) or to create spans inside a trace.

Here is an example of a `FrancophoneService` which methods are traced.

[source, java]
----
import javax.enterprise.context.ApplicationScoped;

import org.eclipse.microprofile.opentracing.Traced;

@Traced
@ApplicationScoped
public class FrancophoneService {

    public String bonjour() {
        return "bonjour";
    }
}
----

NOTE: the best way to add OpenTracing capability to reactive messaging based applications is by adding the `Traced` annotation to all incoming methods.

== Additional instrumentation

The https://github.com/opentracing-contrib[OpenTracing API Contributions project] offers additional instrumentation that can be used to add tracing to a large variety of technologies/components.

The instrumentation documented in this section has been tested with Quarkus and works in both standard and native mode.

=== JDBC

The https://github.com/opentracing-contrib/java-jdbc[JDBC instrumentation] will add a span for each JDBC queries done by your application, to enable it, add the following dependency to your pom.xml:

[source, xml]
----
<dependency>
    <groupId>io.opentracing.contrib</groupId>
    <artifactId>opentracing-jdbc</artifactId>
</dependency>
----

As it uses a dedicated JDBC driver, you must configure your datasource and Hibernate to use it.

[source, properties]
----
quarkus.datasource.db-kind=postgresql
# add ':tracing' to your database URL
quarkus.datasource.jdbc.url=jdbc:tracing:postgresql://localhost:5432/mydatabase
# use the 'TracingDriver' instead of the one for your database
quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver
# configure Hibernate dialect
quarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQLDialect
----


=== Kafka

The https://github.com/opentracing-contrib/java-kafka-client[Kafka instrumentation] will add a span for each message sent to or received from a Kafka topic. To enable it, add the following dependency to your pom.xml:

[source, xml]
----
<dependency>
    <groupId>io.opentracing.contrib</groupId>
    <artifactId>opentracing-kafka-client</artifactId>
    <version>${opentracing-kafka.version}</version>
</dependency>
----

It contains OpenTracing interceptors that must be registered on Kafka producers and consumers.

If you followed the link:kafka[Kafka guide], the interceptors can be added on the `generated-price` and the `prices` channels as follows:

[source, properties]
----
# Configure the Kafka sink (we write to it)
mp.messaging.outgoing.generated-price.connector=smallrye-kafka
mp.messaging.outgoing.generated-price.topic=prices
mp.messaging.outgoing.generated-price.value.serializer=org.apache.kafka.common.serialization.IntegerSerializer
mp.messaging.outgoing.generated-price.interceptor.classes=io.opentracing.contrib.kafka.TracingProducerInterceptor

# Configure the Kafka source (we read from it)
mp.messaging.incoming.prices.connector=smallrye-kafka
mp.messaging.incoming.prices.value.deserializer=org.apache.kafka.common.serialization.IntegerDeserializer
mp.messaging.incoming.prices.interceptor.classes=io.opentracing.contrib.kafka.TracingConsumerInterceptor
----

NOTE: `interceptor.classes` accept a list of classes separated by a comma.

[[configuration-reference]]
== Jaeger Configuration Reference

include::{generated-dir}/config/quarkus-jaeger.adoc[leveloffset=+1, opts=optional]
