Support Eclipse MicroProfile OpenTracing

In  microprofile

Overview

In order to improve Observability of applications deployed in WildFly it would be beneficial to provide transparent tracing of Java EE components via automatic initialization of a tracer (Jaeger) plus a set of instrumentation libraries for components commonly used in Java EE applications, such as JAX-RS and CDI.

This will be implemented by supporting Eclipse MicroProfile OpenTracing 1.1 for applications deployed in WildFly. The integration uses the smallrye-opentracing component to provide the MicroProfile OpenTracing implementation.

For WildFly 14, this shall be marked as "Tech Preview", to get community feedback before committing to a stable API. Notably, this first version lacks any configuration option following WildFly’s standard management model, as this is something that will likely change before a stable version.

Jaeger is composed by:

  • the Jaeger Client, which is the Java library responsible for sending spans to an Agent or Collector. This is added as dependency to applications being deployed into WildFly as part of this proposal

  • Jaeger Agent, which is a daemon typically running on localhost acting as a buffer, accepting spans via UDP and sending them to a remote Collector

  • Jaeger Collector, which is a backend service connected to a permanent storage for writing, receiving spans either from Agents or directly from applications via HTTP

  • Jaeger Query / UI, which is a frontend service connected to the permanent storage for reading, providing a query and web user interface

By default, the Jaeger Client sends spans to an Agent via UDP, close to a "fire and forget" mode. Due to the nature of UDP, the Client isn’t aware that the Agent received the submitted packet containing the span. Similarly, if the cluster of Jaeger Collectors isn’t available, the Jaeger Client won’t break.

Logging options are provided at the Client side (see [JAEGER_REPORTER_LOG_SPANS](https://github.com/jaegertracing/jaeger-client-java/blob/master/jaeger-core/README.md)), as well as Agent and Collector under debug level, for positive confirmation about the flow of spans from the Client up to the Collector.

Issue Metadata

Issue

  • EAP7-1027

  • CLOUD-2728 - Expose EAP "Tracing" information so that it can be consumed by OpenShift Console

  • TRACING-85 - Create jboss-modules for OpenTracing and Jaeger

  • TRACING-87 - OpenTracing integration for JAX-RS in Wildfly

Dev Contacts

QE Contacts

Affected Projects or Components

The implementation of Eclipse MicroProfile OpenTracing is provided by smallrye-opentracing.

Other Interested Projects

  • None

Requirements

  • Support Eclipse MicroProfile OpenTracing 1.1 for applications deployed in WildFly, including JAX-RS and CDI integration. Passing the TCK is required.

  • Support a concrete tracer, such as Jaeger’s

  • Allow applications to supply their own tracers via TracerResolver

  • Each individual application deployed (WAR) should have its own Tracer instance

  • Each WAR within an EAR should be treated as an individual WAR, having their own Tracer instance

Nice-to-Have Requirements

Items that are currently being considered for the next version of this feature:

  • Enable/disable tracing on the entire server

  • Enable/disable tracing on a per-deployment basis

  • Configuration following WildFly’s standard management model

Non-Requirements

  • None at this point

Implementation Plan

  • Add dependencies to io.smallrye:smallrye-opentracing artifacts, including its transitive dependencies (notably OpenTracing)

  • Add dependencies to io.jaegertracing:jaeger-client artifacts, including its transitive dependencies

  • Add a new microprofile-opentracing-smallrye extension to provide OpenTracing support for deployments.

  • Provide a servlet context initializer to initialize Jaeger Tracer

  • Provide the required filters to get SmallRye’s JAX-RS integration working

  • Provide the required CDI extensions and producers to get SmallRye’s CDI integration working

Test Plan

  • smallrye-opentracing component is passing the MicroProfile OpenTracing TCK during its release process.

  • WildFly integration test suite will be enhanced with tests that ensure applications getting deployed are able to be traced. Among possibly others, tests should cover that:

    • A Tracer can be injected into managed beans

    • Tracing can be disabled for specific endpoints/CDI beans by using the @Traced annotation

    • Operation names can be customized by using the @Traced annotation

Community Documentation

The feature will be documented in WildFly Admin Guide (in a new MicroProfile OpenTracing section).