Enable explicit distributed tracing code instrumentation

Use the @Traced annotation to instrument classes and methods for OpenTracing.

Apply the @Traced annotation to specify a class or method to be traced for OpenTracing.

For migrating to later versions of OpenTracing: Both mpOpentracing-1.1 and opentracing-1.1 features have changed its dependency on OpenTracing API to version 0.31.0. If we are using @Traced annotation in the applications, no change is required. If we have code that uses io.opentracing.ActiveSpan and io.opentracing.ActiveSpanSource from version 0.30.0, we must migrate those applications to version 0.31.0. Stabilized features: The MicroProfile OpenTracing 1.3 feature is stabilized. The strategic alternative is mpTelemetry-1.0, a MicroProfile Telemetry feature.

See the MicroProfile OpenTracing to MicroProfile Telemetry 1.0 migration document.

1. Apply the @Traced annotation to a class or method.

   • When you apply the @Traced annotation to a class, the annotation is applied to all methods of that class.

   • If we apply the @Traced annotation to a class and a method, the annotation that is applied to the method takes precedence. The annotation starts a span at the beginning of the method and finishes the span at the end of the method.

2. Optional: Apply arguments to the @Traced annotation.

   value=[true|false]

   The value=[true] argument is the default.

   Use @Traced(false) to annotate specific methods and to disable the creation of a span for those methods. We can also use @Traced(false) to disable span creation of a specific JAX-RS endpoint. When using @Traced(false) for a JAX-RS endpoint method, the upstream SpanContext is not extracted. Any spans that we create, either automatically for outbound requests or explicitly with an injected tracer, do not have an upstream parent span in the span hierarchy. By default, the program traces all JAX-RS endpoint methods.

   operationName=<Name for the span>

   The default value is double quotation marks ("").

   If we use double quotation marks ("") for the operationName value, the @Traced annotation uses the default operation name. If the annotated method is not a JAX-RS endpoint, the default operation name of the new span for the method has the <package name>.<class name>.<method name> values. If we specify the operationName value on a class, the class uses that operationName value for all methods of the class unless a method explicitly overrides it with its own operationName value.

   The following example shows the optional arguments for the @Traced annotation:

   @InterceptorBinding
   @Target({ TYPE, METHOD })
   @Retention(RUNTIME)
   public @interface Traced {     @Nonbinding
       boolean value() default true;
       @Nonbinding
       String operationName() default "";
   }

3. Access the configured tracer.

   1. Use the underlying OpenTracing tracer object configured instance. Set the MicroProfile implementation to use the configured tracer with Contexts and Dependency Injection (CDI).
   2. Access the configured tracer object by injecting the tracer class previously configured for the particular application for this environment. Each application receives a different tracer instance. The tracer object enables support for complex tracing requirements, such as creating spans inside business methods. The following example displays an injected tracer class:

      @Inject
      io.opentracing.Tracer configuredTracer;

   3. Add tags, logs, and baggage to the spans, as shown in the following example:

      configuredTracer.activeSpan().setTag(...);
      configuredTracer.activeSpan().log(...);
      configuredTracer.activeSpan().setBaggage(...);