Using Jaeger to trace an Apache Camel application

Apache Camel has included support for distributed tracing using OpenTracing since Camel version 2.19.0. OpenTracing is a vendor neutral API to enable applications to report tracing information to a backend for storage, analysis and visualisation.

In this article we will show how two Apache Camel examples can be easily updated to enable the distributed tracing information to be reported to Jaeger.

If you don’t already have a copy of Apache Camel, then download the latest version from the download page. Before we look at the examples, we need to start an instance of the Jaeger backend and access the UI. Instructions for this can be found here. The following examples will be using the latest Jaeger java client, version 0.30.3 at the time of writing.

Camel OpenTracing Example

This example can be found in the “examples/camel-example-opentracing” folder. Follow the instructions in the readme to build and run the example as distributed with Camel. The example uses a simple logging tracer that outputs the distributed tracing (span) information to the console.

To change this example to use Jaeger there are two steps:

• We simply need to edit the pom.xml files in client, service1 and service2 folders to replace the example logging based tracer:

<dependency>
  <groupId>org.apache.camel.example</groupId>
  <artifactId>camel-example-opentracing-loggingtracer</artifactId>
  <version>${project.version}</version>
</dependency>

with the Jaeger java client:

<dependency>
  <groupId>io.jaegertracing</groupId>
  <artifactId>jaeger-client</artifactId>
  <version>${jaeger.version}</version>
</dependency>

• The only other change is to supply the service name as an environment variable or system property. So the simplest approach is just to run the following in each of the service command windows, where “<name>” would be client, service1 or service2:

export JAEGER_SERVICE_NAME=<name>

NOTE: By default the Jaeger java client will use a probabilistic sampler set to report every 1000th trace instance. For testing purposes, we can configure it to report every instance by setting the environment variable “JAEGER_SAMPLER_PARAM=1.0”. This only needs to be set in the command window running the client, as the client is responsible for making the sampling decision that is then propagated to the other two services.

Once the services have been started and the client has triggered at least one request, you can now open the Jaeger UI selecting the “client” service to see the captured traces. If you select one, then the details view will show the interactions between client, service1 and service2 (unexpanded version shown in the image at the top of this article). Notice that log information is also captured from the Camel route.

Camel JMS Loan Broker Example

Unlike the previous example, the JMS loan broker example has no OpenTracing support “out of the box”. This example can be found in the “examples/camel-example-loan-broker-jms” folder.

Instructions for adding OpenTracing support to a Camel application show there are three different ways. If the example was using Spring Boot, then this would be as simple as adding a single @CamelOpenTracing annotation to the application.

However in the case of this example we need to use the explicit programmatic approach. Follow these steps:

• Add these dependencies to the pom.xml:

    <dependency>
      <groupId>org.apache.camel</groupId>
      <artifactId>camel-opentracing</artifactId>
    </dependency>
    <dependency>
      <groupId>io.jaegertracing</groupId>
      <artifactId>jaeger-client</artifactId>
      <version>${jaeger.version}</version>
    </dependency>

• Update “org.apache.camel.loanbroker.Client”

import org.apache.camel.opentracing.OpenTracingTracer;
    ....
    CamelContext context = applicationContext.getBean("camel", CamelContext.class);
    context.start();
    OpenTracingTracer ottracer = new OpenTracingTracer();
    ottracer.init(context);
    ....

• Update “org.apache.camel.loanbroker.LoanBrokerRoute”

import org.apache.camel.opentracing.OpenTracingTracer;
....
public void configure() {
    OpenTracingTracer ottracer = new OpenTracingTracer();
    ottracer.init(getContext());
    ....

• Follow the steps in the readme to run the example, making sure the JAEGER_SERVICE_NAME (and possibly JAEGER_SAMPLER_PARAM) environment variable is exported first for the client and loan broker. This should result in a trace as below:

Note: in this example, the spans representing the messaging sends and receives are using “span.kind” tags of consumer and producer. These represent asynchronous messaging communications, whereas the client and server span kinds are generally used for RPC communications.

This article has shown how to quickly add OpenTracing instrumentation to some Camel examples and use Jaeger to store and visualise the trace instances.

If you have questions regarding Jaeger, then please contact us. If you have suggestions for improvements to the OpenTracing support in Apache Camel, please create a jira.