Versions Compared

Old Version 50

changes.mady.by.user Andriy Redko

Saved on

compared with

New Version Current

changes.mady.by.user Andriy Redko

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Warning

The Apache HTrace project has retired on 2018-04-11 and is not developed anymore. The Apache CXF retired the Apache HTrace integration, starting from 3.3.0 release. 

Overview

Apache HTrace is a tracing framework intended for use with distributed systems written in java. Since version 3.1.3, Apache CXF fully supports integration with Apache HTrace, both on client side and server side. This section gives a complete overview on how distributed tracing support is supported in JAX-RS applications built on top of Apache CXF.

...

Code Block
java
java
final Map<String, String> properties = new HashMap<String, String>();
properties.put(Tracer.SPAN_RECEIVER_CLASSES_KEY, ...);
properties.put(Tracer.SAMPLER_CLASSES_KEY, ...);

final JAXRSServerFactoryBean factory = 
    RuntimeDelegate.getInstance().createEndpoint(/* application instance */, JAXRSServerFactoryBean.class);
factory.setFeatures(Arrays.< Feature >asList(new HTraceFeature(HTraceConfiguration.fromMap(properties), "tracer")));
...
return factory.create();

...

In the following subsections we are going to walk through many different scenarios to illustrate the distributed tracing in action, starting from the simplest ones and finishing with asynchronous JAX-RS services. All examples assume that configuration has been done (see please Configuring Client and Configuring Server sections above).

Example #1: Client and Server with default distributed tracing configured

...

Info

Configuring right phases for interceptors is very important. The recommended phase for in-interceptor is PRE_INVOKE while for out-interceptor is PREPOST_MARSHAL. If wrong phases are being used, response or/and request headers, status code, etc could be ignored or not processed.

...

Code Block
bash
bash
[INFO] [-, -] 2017-03-11 14:40:13.603 org.eclipse.jetty.server.Server Started @2731ms
[INFO] [tracer-server/192.168.0.101, span: 6d3e0d975d4c883cce12aee1fd8f3e7e] 
2017-03-11 14:40:24.013 com.example.rs.PeopleRestService Getting all employees
[INFO] [tracer-server/192.168.0.101, span: 6d3e0d975d4c883c7592f4c2317dec22] 
2017-03-11 14:40:28.017 com.example.rs.PeopleRestService Looking up manager in the DB database

The special [-, -] placeholder indicates that no trace details are being available at the moment of logging the record.

Accessing Apache HTrace APIs

The Apache CXF  abstracts as much of the tracer-specific APIs behind TracerContext as possible. However, sometimes there is a need to get access to Apache HTrace APIs in order to leverages the available instrumentations. To make it possible, TracerContext has a dedicated unwrap method which returns underlying Tracer instance.

Code Block
java
java
@GET
@Path("/search")
@Produces(MediaType.APPLICATION_JSON)
public JsonObject search(@QueryParam("q") final String query, @Context final TracerContext tracing) throws Exception {
    final Tracer tracer = tracing.unwrap(Tracer.class);
    // ...
}

Future Work

The Apache CXF is very proud to offer Apache HTrace integration. At the current stage, it was a conscious decision to keep the minimal API and provide the set of necessary features only. However, there is a strong commitment to evolve not only Apache HTrace integration, but the distributed tracing support in general.