Enabling explicit distributed tracing code instrumentation

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

About this task

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 you are using @Traced annotation in your applications, no change is required. If you have code that uses io.opentracing.ActiveSpan and io.opentracing.ActiveSpanSource from version 0.30.0, you 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. For more information, see the MicroProfile OpenTracing to MicroProfile Telemetry 1.0 migration document.

Procedure

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 you 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.
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. You can also use @Traced(false) to disable span creation of a specific JAX-RS endpoint. When you use @Traced(false) for a JAX-RS endpoint method, the upstream SpanContext is not extracted. Any spans that you 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 you 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 you 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 "";
}
```
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 that you 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(...);
```