Overview

OpenTracing is a vendor-neutral open standard for distributed tracing. Essentially, for Java-based projects the specification exists as a set of Java APIs which any distributed tracing solution is welcome to implement. There are quite a few distributed tracing frameworks available which are compatible with OpenTracing, notably Zipkin (via community contributions like bridge from Brave to OpenTracing ), Lightstep and Jaeger. Starting from 3.2.1 release, Apache CXF fully supports integration (through cxf-integration-tracing-opentracing module) with any distributed tracer that provides OpenTracing Java API implementation.

The section dedicated to Apache HTrace has pretty good introduction into distributed tracing basics however OpenTracing specification abstracts a lot of things, outlining just a general APIs to denote the Span lifecycle and injection points to propagate the context across many distributed components. As such, the intrinsic details about HTTP headers f.e. becomes an integral part of the distributed tracer of your choice, out of reach for Apache CXF.

Distributed Tracing in Apache CXF using OpenTracing

Apache CXF is a very popular framework for building services and web APIs. No doubts, it is going to play even more important role in context of microservices architecture letting developers to quickly build and deploy individual JAX-RS/JAX-WS services. Distributed tracing is an essential technique to observe the application platform as a whole, breaking the request to individual service traces as it goes through and crosses the boundaries of threads, processes and machines.

The current integration of distributed tracing in Apache CXF supports OpenTracing Java API 0.30.0+ and provides full-fledged support of JAX-RS 2.x / JAX-WS applications. From high-level prospective, the JAX-RS integration consists of three main parts:

• TracerContext (injectable through @Context annotation)
• OpenTracingProvider (server-side JAX-RS provider) and OpenTracingClientProvider (client-side JAX-RS provider)
• OpenTracingFeature (server-side JAX-RS feature) to simplify the configuration and integration

Similarly, from high-level perspective, JAX-WS integration includes:

• OpenTracingStartInterceptor / OpenTracingStopInterceptor / OpenTracingFeature Apache CXF feature (server-side JAX-WS support)
• OpenTracingClientStartInterceptor / OpenTracingClientStopInterceptor / OpenTracingClientFeature Apache CXF feature (client-side JAX-WS support)

Apache CXF uses HTTP headers to hand off tracing context from the client to the service and from the service to service. Those headers are specific to distributing tracing framework you have picked and are not configurable at the moment (unless the framework itself has a way to do that).

By default, OpenTracingClientProvider will try to pass the currently active span through HTTP headers on each service invocation. If there is no active spans, the new span will be created and passed through HTTP headers on per-invocation basis. Essentially, for JAX-RS applications just registering OpenTracingClientProvider on the client and OpenTracingProvider on the server is enough to have tracing context to be properly passed everywhere. The only configuration part which is necessary are span reports(s) and sampler(s) which are, not surprisingly, specific to distributing tracing framework you have chosen.

It is also worth to mention the way Apache CXF attaches the description to spans. With regards to the client integration, the description becomes a full URL being invoked prefixed by HTTP method, for example: GET http://localhost:8282/books. On the server side integration, the description becomes a relative JAX-RS resource path prefixed by HTTP method, f.e.: GET books, POST book/123