image:https://semaphoreci.com/api/v1/smallrye/smallrye-opentracing/branches/master/badge.svg["Semaphore CI", link="https://semaphoreci.com/smallrye/smallrye-opentracing"]
image:https://img.shields.io/github/license/smallrye/smallrye-opentracing.svg["License", link="http://www.apache.org/licenses/LICENSE-2.0"]

= SmallRye OpenTracing

SmallRye OpenTracing is an implementation of https://github.com/eclipse/microprofile-opentracing meant
to be reusable for different vendors.

== How to use

The following components have to be added to deployment to pass `microprofile-opentracing-tck`:

=== Server side JAX-RS

Server side JAX-RS tracing integration is provided by JAX-RS `SmallRyeTracingDynamicFeature` and
servlet filter `SpanFinishingFilter` which finishes the span started in JAX-RS filter.

The installation is JAX-RS and server implementation specific.
For example in RestEasy `DynamicFeature` it can be enabled by specifying
`resteasy.providers` in servlet context init parameters. The following code snippet demonstrates
possible installation.

```java
public class ServletContextTracingInstaller implements ServletContextListener {

  @Override
  public void contextInitialized(ServletContextEvent servletContextEvent) {
    ServletContext servletContext = servletContextEvent.getServletContext();
    servletContext.setInitParameter("resteasy.providers", SmallRyeTracingDynamicFeature.class.getName());

    Dynamic filterRegistration = servletContext.addFilter("tracingFilter", new SpanFinishingFilter());
    filterRegistration.setAsyncSupported(true);
    filterRegistration.addMappingForUrlPatterns(EnumSet.allOf(DispatcherType.class), true, "*");
  }
}
```

=== Client side JAX-RS

Vendor has to implement `ClientTracingRegistrarProvider` and specify it in
`META-INF/services/org.eclipse.microprofile.opentracing.ClientTracingRegistrarProvider`.

This project provides `SmallRyeClientTracingFeature` with tracing integration. The feature
has to be registered to `ClientBuilder` in vendor specific implementation of `ClientTracingRegistrarProvider`.
Client side tracing usually requires more components, for example OpenTracing-aware `AsyncExecutor`.

=== MicroProfile Rest Client
The Rest Client instrumentation is provided in `SmallRyeRestClientListener` which has to be registered
in `META-INF/services/org.eclipse.microprofile.rest.client.spi.RestClientListener`.

=== CDI

The `@Traced` aspects of the specification is provided by the `OpenTracingInterceptor`, from the
link:https://github.com/opentracing-contrib/java-interceptors[OpenTracing Contrib Java Interceptors] project.

=== Tracer producer

Vendor has to provide CDI tracer producer. It is not provided by this library as the
tracer resolution is not defined by MicroProfile specification.

== Develop

```bash
mvn clean install
```

=== Debug

Debug of the deployment can be enabled in `arquillian.xml` configuration file.

Run the following to debug tests on port `8788`.
```bash
mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8788 -Xnoagent -Djava.compiler=NONE" test
```

== Release

The release process is done automatically via CI integration. For more information see link:https://groups.google.com/forum/#!topic/smallrye/Ct4-k3L-JbA[Release process].
Before releasing make sure that the current version in `pom.xml` matches specification version.
To update the version run `mvn --batch-mode release:update-versions -DdevelopmentVersion=1.2.0-SNAPSHOT`.
Now the artifact can be release for specification version `1.2`.
