Chapter 19. Eclipse MicroProfile

19.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 Java Client as the default tracer and provides a set of instrumentation libraries for components commonly used in Java EE applications, such as JAX-RS and CDI. 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 CDI beans and other JAX-RS endpoints, and how to implement a custom tracer.

19.1.1. Enable or Disable Tracing for CDI Beans

As defined by the Eclipse MicroProfile OpenTracing specification, CDI 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 CDI 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() {
    }
}

19.1.2. Enable or Disable Tracing for JAX-RS Endpoints

JAX-RS endpoints are traced by default if the microprofile-opentracing-smallrye subsystem is present in the server configuration.

To disable tracing for JAX-RS endpoints, add the @Traced(false) annotation to the JAX-RS endpoint at the class or method level as described in Enable or Disable Tracing for CDI Beans above.

19.1.3. Implement a Custom Tracer

If you need something more complex than what is provided by the default Jaeger Java 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();
    }
}

19.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.

19.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 CDI 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"
        }]
    }
}