components/camel-opentracing/src/main/docs/opentracing.adoc

[[OpenTracing-OpenTracingComponent]]
= OpenTracing Component

*Since Camel 2.19*

The OpenTracing component is used for tracing and timing incoming and
outgoing Camel messages using http://opentracing.io/[OpenTracing].

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

See the http://opentracing.io/[OpenTracing] website for a list of supported tracers.


== Configuration

The configuration properties for the OpenTracing tracer are:

[width="100%",cols="10%,10%,80%",options="header",]
|=======================================================================
|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.

|=======================================================================


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`.

[source,java]
--------------------------------------------------------------------------------------------------
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.

[source,xml]
---------------------------------------------------------------------------------------------------------
  <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.

// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

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

[source,xml]
----
<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.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| 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
|===
// spring-boot-auto-configure options: END

== 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:

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

IMPORTANT: 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 https://github.com/apache/camel/tree/master/examples/camel-example-opentracing[camel-example-opentracing] 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:
https://github.com/apache/camel/tree/master/examples/camel-example-opentracing[camel-example-opentracing]