AWS XRay

Since Camel 2.21

The camel-aws-xray component is used for tracing and timing incoming and outgoing Camel messages using AWS XRay.

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

Configuration

The configuration properties for the AWS XRay tracer are:

Option Default Description

addExcludePatterns

 

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 matching routeId’s. The pattern uses the rules from Intercept.

setTracingStrategy

NoopTracingStrategy

Allows a custom Camel InterceptStrategy to be provided in order to track invoked processor definitions like BeanDefinition or ProcessDefinition. TraceAnnotatedTracingStrategy will track any classes invoked via .bean(…​) or .process(…​) that contain a @XRayTrace annotation at class level.

There is currently only one way an AWS XRay tracer can be configured to provide distributed tracing for a Camel application:

Explicit

Include the camel-aws-xray component in your POM, along with any specific dependencies associated with the AWS XRay Tracer.

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

XRayTracer xrayTracer = new XRayTracer();
// By default it uses a NoopTracingStrategy, but you can override it with a specific InterceptStrategy implementation.
xrayTracer.setTracingStrategy(...);
// And then initialize the context
xrayTracer.init(camelContext);

To use XRayTracer in XML, all you need to do is to define the AWS XRay tracer bean. Camel will automatically discover and use it.

  <bean id="tracingStrategy" class="..."/>
  <bean id="aws-xray-tracer" class="org.apache.camel.component.aws.xray.XRayTracer">
    <property name="tracer" ref="tracingStrategy"/>
  </bean>

In case of the default NoopTracingStrategy only the creation and deletion of exchanges is tracked but not the invocation of certain beans or EIP patterns.

Tracking of comprehensive route execution

In order to track the execution of an exchange among multiple routes, on exchange creation a unique trace ID is generated and stored in the headers if no corresponding value was yet available. This trace ID is copied over to new exchanges in order to keep a consistent view of the processed exchange.

As AWS XRay traces work on a thread-local basis the current sub/segment should be copied over to the new thread and set as explained in in the AWS XRay documentation. The Camel AWS XRay component therefore provides an additional header field that the component will use in order to set the passed AWS XRay Entity to the new thread and thus keep the tracked data to the route rather than exposing a new segment which seems uncorrelated with any of the executed routes.

The component will use the following constants found in the headers of the exchange:

Header Description

Camel-AWS-XRay-Trace-ID

Contains a reference to the AWS XRay TraceID object to provide a comprehensive view of the invoked routes

Camel-AWS-XRay-Trace-Entity

Contains a reference to the actual AWS XRay Segment or Subsegment which is copied over to the new thread. This header should be set in case a new thread is spawned and the performed tasks should be exposed as part of the executed route instead of creating a new unrelated segment.

Note that the AWS XRay Entity (i.e., Segment and Subsegment) are not serializable and therefore should not get passed to other JVM processes.

Example

You can find an example demonstrating the way to configure AWS XRay tracing within the tests accompanying this project.

Dependency

In order to include AWS XRay support into Camel, the archive containing the Camel related AWS XRay related classes need to be added to the project. In addition to that, AWS XRay libraries also need to be available.

To include both, AWS XRay and Camel, dependencies use the following Maven imports:

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-xray-recorder-sdk-bom</artifactId>
        <version>2.4.0</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
      <dependency>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-aws-xray</artifactId>
      </dependency>

      <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-xray-recorder-sdk-core</artifactId>
      </dependency>
      <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
      </dependency>
  </dependencies>