OpenTracing

Since Camel 2.19

The OpenTracing component is used for tracing and timing incoming and outgoing Camel messages using OpenTracing.

Events (spans) are captured for incoming and outgoing messages being sent to/from Camel.

See the OpenTracing website for a list of supported tracers.

Configuration

The configuration properties for the OpenTracing tracer are:

Option Default Description

excludePatterns

Sets exclude pattern(s) that will disable tracing for Camel messages that matches the pattern. The content is a Set<String> where the key is a pattern. The pattern uses the rules from Intercept.

encoding

false

Sets whether the header keys need to be encoded (connector specific) or not. The value is a boolean. Dashes need for instances to be encoded for JMS property keys.

setTracingStrategy

NoopTracingStrategy

Allows a custom Camel InterceptStrategy to be provided in order to augment the default Spans with data from each processor in a route. OpenTracingTracingStrategy will create spans for each processor, except for Camel log and OpenTracing processors, and activate a Scope in order to enable third-party instrumentation in processors through the default ScopeManager. Processor spans can be excluded through the exludePatterns set, these will be matched using the processor’s ID.

There are three ways in which an OpenTracing tracer can be configured to provide distributed tracing for a Camel application:

Explicit

Include the camel-opentracing component in your POM, along with any specific dependencies associated with the chosen OpenTracing compliant Tracer.

To explicitly configure OpenTracing support, instantiate the OpenTracingTracer and initialize the camel context. You can optionally specify a Tracer, or alternatively it can be implicitly discovered using the Registry or ServiceLoader.

OpenTracingTracer ottracer = new OpenTracingTracer();
// By default it uses a Noop Tracer, but you can override it with a specific OpenTracing implementation.
ottracer.setTracer(...);
// And then initialize the context
ottracer.init(camelContext);

To use OpenTracingTracer in XML, all you need to do is to define the OpenTracing tracer beans. Camel will automatically discover and use them.

  <bean id="tracer" class="..."/>
  <bean id="ottracer" class="org.apache.camel.opentracing.OpenTracingTracer">
    <property name="tracer" ref="tracer"/>
  </bean>

Spring Boot

If you are using Spring Boot then you can add the camel-opentracing-starter dependency, and turn on OpenTracing by annotating the main class with @CamelOpenTracing.

The Tracer will be implicitly obtained from the camel context’s Registry, or the ServiceLoader, unless a Tracer bean has been defined by the application.

Java Agent

The third approach is to use a Java Agent to automatically configure the OpenTracing support.

Include the camel-opentracing component in your POM, along with any specific dependencies associated with the chosen OpenTracing compliant Tracer.

The OpenTracing Java Agent is associated with the following dependency:

    <dependency>
      <groupId>io.opentracing.contrib</groupId>
      <artifactId>opentracing-specialagent</artifactId>
    </dependency>
It is necessary to use an OpenTracing compliant tracer that is compatible with OpenTracing Java API version 0.31 or higher.

The Tracer used will be implicitly loaded from the camel context Registry or using the ServiceLoader.

How this agent is used will be specific to how you execute your application. Service2 in the Opentracing Spring Boot example downloads the agent into a local folder and then uses the exec-maven-plugin to launch the service with the -javaagent command line option.

Example

You can find an example demonstrating the three ways to configure OpenTracing here: camel-example-spring-boot-opentracing

Spring Boot Auto-Configuration

When using opentracing with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-opentracing-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>

The component supports 2 options, which are listed below.

Name Description Default Type

camel.opentracing.encoding

Activate or deactivate dash encoding in headers (required by JMS) for messaging.

Boolean

camel.opentracing.exclude-patterns

Sets exclude pattern(s) that will disable tracing for Camel messages that matches the pattern.

Set

Span Operations Processors

The OpenTracing Component exposes the Java API span operations as a set of Processors: TagProcessor, SetBaggageProcessor, and GetBaggageProcessor.

Example

from("seda:a").routeId("a")
        .process(new SetBaggageProcessor("a-baggage", simple("${header.request-header}")))
        .to("seda:b")
        .to("seda:c");

from("seda:b").routeId("b")
        .process(new TagProcessor("b-tag", simple("${header.request-header}")));

from("seda:c").routeId("c")
        .process(new GetBaggageProcessor("a-baggage", "baggage-header"));

Where the value of header "request-header" is "foo", the resulting trace from executing route "seda:a" would include:

  • Span "a" with a baggage item named "a-baggage" of value "foo"

  • Span "b" with a tag named "b-tag" of value "foo"

and the resulting message would contain:

  • Header "baggage-header" of value "foo"

MDC Logging

When MDC Logging is enabled for the active Camel context the Trace ID and Span ID will be added and removed from the MDC for each route or processor (depending on the tracing strategy configured), the keys are traceId and spanId, respectively.

If the OpenTracingTracingStrategy is enabled the span ID will be the one for the current processor that logs an entry, otherwise it will be the one for the current route.

Back to top