smallrye/smallrye-opentracing

:ci: https://github.com/smallrye/smallrye-opentracing/actions/workflows/build.yml/

image:https://github.com/smallrye/smallrye-opentracing/actions/workflows/build.yml/badge.svg?branch=main[link={ci}] image:https://img.shields.io/github/license/smallrye/smallrye-opentracing.svg["License", link="http://www.apache.org/licenses/LICENSE-2.0"] image:https://img.shields.io/maven-central/v/io.smallrye/smallrye-opentracing?color=green[]

= SmallRye OpenTracing (Deprecated)

OpenTracing is no longer under development and was replaced by OpenTelemetry Tracing. In the future, please refer to SmallRye OpenTelemetry: https://github.com/smallrye/smallrye-opentelemetry

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.

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

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.

mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8788 -Xnoagent -Djava.compiler=NONE" test

smallrye / smallrye-opentracing

readme