opentracing-java-aws-xray

Java OpenTracing implementation backed by AWS X-Ray.

WARNING: this code is currently in beta: please test thoroughly before deploying to production, and report any issues.

Overview

The OpenTracing specification is a vendor-neutral API for instrumentation and distributed tracing. This library provides an implementation which is backed by the AWS X-Ray Java SDK, and for the most part just provides a thin wrapper around the underlying X-Ray classes.

Using this library

The code is not yet being deployed to Maven central (we're working on that!), so you'll have to build your own version. This should be as simple as:

cloning this repository locally
running mvn package [1]
including the resulting JAR file in your /lib folder (or similar)

[1] If you don't already have Maven installed, you can use the mvnw command (or mvnw.cmd for Windows) instead which uses the Maven wrapper plugin to download and start the correct version of Maven.

AWS compatibility

Integrating with AWS systems

Since this library mostly just wraps the standard X-Ray classes, it should work seamlessly in code which makes use of multiple AWS services: the standard AWS SDK will add the necessary trace headers automatically, and recover them on remote servers (e.g. when invoking lambda functions). However, this hasn't yet been extensively tested, so feedback and bug reports are very welcome!

Naming conventions

The OpenTracing standard and the AWS X-Ray system each use different naming conventions for some of the same concepts (e.g. HTTP response codes). Since the goal of this project is to largely hide the fact that we're using X-Ray under the hood, and to only expose the OpenTracing API:

client code should prefer using the OpenTracing naming conventions for tag names (however, if you supply the X-Ray-specific names, values will still end up in the right place)
this library will silently convert some known tag names values to their X-Ray equivalents
X-Ray traces further subdivide tagged values into separate sub-objects for e.g. HTTP request and response data:
- where possible, ensure values end up in the correct place on the trace
- all other values are stored in the metadata section, under a default namespace if not specified
- see the X-Ray Segment Documents for further details

The following OpenTracing names will be translated to fit the X-Ray names:

OpenTracing tag name	X-Ray trace name
`version`	`service.version`
`db.instance`	`sql.url`
`db.statement`	`sql.sanitized_query`
`db.type`	`sql.database_type`
`db.user`	`sql.user`
`db.driver`	`sql.driver`
`db.version`	`sql.version`
`http.method`	`http.request.method`
`http.url`	`http.request.url`
`http.client_ip`	`http.request.client_ip`
`http.user_agent`	`http.request.user_agent`
`http.status_code`	`http.response.status`
`http.content_length`	`http.response.content_length`
`foo`	`metadata.default.foo`
`widget.foo`	`metadata.widget.foo`

Additionally, the following special tag names are defined in AWSXRayTags and can be used to directly modify the behaviour of the underlying X-Ray trace Entity (NB some of these only work for Segment, i.e. top-level spans):

	Behaviour	`Segment`	`Subsegment`
`error`	sets the `isError()` flag	Y	Y
`fault`	sets the `isFault()` flag	Y	Y
`throttle`	sets the `isThrottle()` flag	Y	Y
`isSampled`	sets the `isSampled()` flag	Y	-
`user`	sets the `user` value	Y	-
`origin`	sets the `origin` value	Y	-
`parentId`	sets the `parentId` value	Y	Y

Context injection / extraction

This library supports basic injection and extraction of SpanContext:

in most cases it is expected that this library will be used in AWS-hosted systems, and calls between AWS services using the official SDK will already handle passing trace IDs across so no further work is required
for non-AWS systems, the current SpanContext can be converted into e.g. a set of HTTP headers using Tracer.inject and sent over the wire; on the other side, Tracer.extract can be used to convert the headers back into a SpanContext
for compatibility between AWS and non-AWS services, we store the trace context information in a single header X-Amzn-Trace-Id - see the Amazon trace header documentation for more details

Known limitations

This library does not currently provide a full implementation of the OpenTracing API: the X-Ray classes themselves already provide some of the same features, and in other cases the APIs are incompatible. The following limitations currently apply:

References

OpenTracing provides for arbitrary references between spans, including parent-child and follows-from relationships. In practice X-Ray only supports parent-child relationships, and each span can have at most one parent. Calls to add references of different types, or multiple parent-child relationships, will generally be ignored.

Logging

OpenTracing provides methods to add logs to the trace. These methods will work as expected: structured data are stored in X-Ray metadata under a "log" namespace, but this approach isn't advised since the resulting JSON format is clunky. A better approach in AWS is to make use of CloudWatch.

License

This project is licensed under the Apache 2.0 License.