| [[OpenTracing-OpenTracingComponent]] |
| = OpenTracing Component |
| :page-source: components/camel-opentracing/src/main/docs/opentracing.adoc |
| |
| *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] |