Chapter 20. Eclipse MicroProfile

20.1. Using Eclipse MicroProfile OpenTracing to Trace Requests

Important

Eclipse Microprofile OpenTracing is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

Eclipse Microprofile OpenTracing functionality is provided by the microprofile-opentracing-smallrye subsystem. This subsystem ships with the Jaeger Client as the default tracer and provides a set of instrumentation libraries for components commonly used in Jakarta EE applications, such as Jakarta RESTful Web Services and Contexts and Dependency Injection. See Tracing Requests with the MicroProfile OpenTracing SmallRye Subsystem in the Configuration Guide for more information about this subsystem.

The following sections describe how to customize tracing for Jakarta Contexts and Dependency Injection beans and other Jakarta RESTful Web Services endpoints, and how to implement a custom tracer.

20.1.1. Enable or Disable Tracing for Jakarta Contexts and Dependency Injection Beans

As defined by the Eclipse MicroProfile OpenTracing specification, Jakarta Contexts and Dependency Injection beans are traced if the org.eclipse.microprofile.opentracing.Traced annotation is present, either at the class or at the method level. Tracing can be disabled by setting the annotation value to false. Similarly, a custom operation name can be set by specifying the parameter operationName for that annotation. The semantics are defined by the MicroProfile OpenTracing specification.

The following example demonstrates how to configure tracing for a Jakarta Contexts and Dependency Injection bean. Note that tracing can be specified at the method level.

import org.eclipse.microprofile.opentracing.Traced;

@Traced
public class TracedBean {
    public void doSomething() {
    }

    @Traced(true)
    public void doSomethingTraced() {
    }

    @Traced(false)
    public void doSomethingNotTraced() {
    }
}

The following example demonstrates how to specify an operation name for the OpenTracing Span for this trace point.

import org.eclipse.microprofile.opentracing.Traced;

@Traced(operationName = "my-custom-class-operation-name")
public class CustomOperationNameBean {

    @Traced(operationName = "my-custom-method-operation-name")
    public void doSomething() {
    }

    @Traced
    public void doSomethingElse() {
    }
}

20.1.2. Enable or Disable Tracing for Jakarta RESTful Web Services Endpoints

Jakarta RESTful Web Services endpoints are traced by default if the microprofile-opentracing-smallrye subsystem is present in the server configuration.

To disable tracing for Jakarta RESTful Web Services endpoints, add the @Traced(false) annotation to the Jakarta RESTful Web Services endpoint at the class or method level as described in Enable or Disable Tracing for Jakarta Contexts and Dependency Injection Beans above.

20.1.3. Implement a Custom Tracer

If you need something more complex than what is provided by the default Jaeger Client, you can provide your own tracer by implementing a TracerResolver that returns the Tracer with the desired state. In this case, the default tracer will not be used.

The following example demonstrates how to create a new implementation of TracerResolver that returns a custom implementation of the Tracer class.

import io.opentracing.Tracer;
import io.opentracing.contrib.tracerresolver.TracerResolver;
import org.myproject.opentracing.CustomTracer;

public static class MyTracerResolver extends TracerResolver {
    @Override
    protected Tracer resolve() {
        return new CustomTracer();
    }
}

20.2. Using Eclipse MicroProfile Health to Monitor Server Health

Important

Eclipse MicroProfile Health is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

Eclipse Microprofile Health functionality is provided by the microprofile-health-smallrye subsystem. See Monitor Server Health Using Eclipse MicroProfile Health in the Configuration Guide for more information about this subsystem.

The following section describe how to implement a custom health check.

20.2.1. Implement a Custom Health Check

The default implementation provided by the microprofile-health-smallrye subsystem performs a basic health check. For more detailed information, on either the server or application status, custom health checks may be included. Any Jakarta Contexts and Dependency Injection beans that include the org.eclipse.microprofile.health.Health annotation at the class level are automatically discovered and invoked at runtime.

The following example demonstrates how to create a new implementation of a health check that returns an UP state.

import org.eclipse.microprofile.health.Health;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;

@Health
public class HealthTest implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("health-test").up().build();
    }
}

Once deployed, any subsequent health check queries will include the custom checks, as seen below.

/subsystem=microprofile-health-smallrye:check
{
    "outcome" => "success",
    "result" => {
        "outcome" => "UP",
        "checks" => [{
            "name" => "health-test",
            "state" => "UP"
        }]
    }
}