Chapter 37. AWS XRay Component
Available as of 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.
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>1.3.1</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>
The configuration properties for the AWS XRay tracer are:
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.
Allows a custom Camel
There is currently only one way an AWS XRay tracer can be configured to provide distributed tracing for a Camel application:
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
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.
37.2.2. 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:
Contains a reference to the AWS XRay
Contains a reference to the actual AWS XRay
Note that the AWS XRay
Subsegment) are not serializable and therefore should not get passed to other JVM processes.
You can find an example demonstrating the way to configure AWS XRay tracing within the tests accompanying this project.