README.md

OpenCensus JAX-RS

The OpenCensus JAX-RS for Java is a container and client filter for trace instrumentation when using JAX-RS for REST implementation in Java.

Quickstart

Add the dependencies to your project

For Maven add to your pom.xml:

<dependencies>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-api</artifactId>
    <version>0.26.0</version>
  </dependency>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-contrib-http-jaxrs</artifactId>
    <version>0.26.0</version>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

compile 'io.opencensus:opencensus-api:0.26.0'
compile 'io.opencensus:opencensus-contrib-http-jaxrs:0.26.0'

Usage

Container Filter

The container filter should be added to the JAX-RS Application class and endpoints should be annotated with @Metrics annotation.

class MyApplication extends Application {
  @Override
  public Set<Class<?>> getClasses() {
      Set<Class<?>> providers = new HashSet<>(super.getClasses());
      providers.add(JaxrsContainerFilter.class);
      return providers;
  }
}

It is possible to customize the filter by using the custom constructor. The below will use the B3Format for context propagation instead of the W3C text context format.

class MyApplication extends Application {
  @Override
  public Set<Object> getSingletons() {
    Set<Object> singletons = new HashSet<>(super.getSingletons());
    singletons.add(new JaxrsContainerFilter(
        new JaxrsContainerExtractor(),
        Tracing.getPropagationComponent().getB3Format(),
        /* publicEndpoint= */ true));
    return singletons;
  }
}

@Metrics
@Path("/resource")
class MyResource {
  @GET
  public Response resource() {
    ...
  }
}

The annotation may also be applied on method level.

Client Filter

Filter should be added to the WebTarget instance when using JAX-RS as client.

WebTarget target = ClientBuilder.newClient().target("endpoint");
target.register(JaxrsClientFilter.class);

It is possible to customize the filter using the custom constructor. The below will use the B3Format for context propagation instead of the default W3C text context format.

WebTarget target = ClientBuilder.newClient().target("endpoint");
target.register(new JaxrsClientFilter(
    new JaxrsContainerExtractor(),
    Tracing.getPropagationComponent().getB3Format()));