MicroProfile Health

Motivation

Health checks are used to probe the state of a computing node from another machine (i.e. kubernetes service controller) with the primary target being cloud infrastructure environments where automated processes maintain the state of computing nodes.

In this scenario, health checks are used to determine if a computing node needs to be discarded (terminated, shutdown) and eventually replaced by another (healthy) instance.

It’s not intended (although could be used) as a monitoring solution for human operators.

Proposed solution

The proposed solution breaks down into two parts:

• A health check protocol and wireformat

• A Java API to implement health check procedures

Detailed design

Protocol

This project defines a protocol (wireformat, semantics and possible forms of interactions) between system components that need to determine the “liveliness” of computing nodes in a bigger architecture. A detailed description of the health check protocol can be found in the companion document.

API Usage

The main API to provide health check procedures on the application level is the HealthCheck interface:

@FunctionalInterface
public interface HealthCheck {

    HealthCheckResponse call();
}

Applications are expected to provide health check procedures (implementation of a HealthCheck), which will be used by the framework or runtime hosting the application to verify the healthiness of the computing node.

The runtime will call() the HealthCheck which in turn creates a HealthCheckResponse that signals the health status to a consuming end:

public class HealthCheckResponse {

    public enum Status { UP, DOWN }

    private final String name;

    private final Status status;

    private final Optional<Map<String, Object>> data;

    [...]
}

Constructing HealthCheckResponse

Application level code is expected to use one of static methods on HealthCheckResponse to retrieve a HealthCheckResponseBuilder used to construct a response, i.e. :

public class SuccessfulCheck implements HealthCheck {
    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("successful-check");
    }
}

Different kinds of Health Checks

This specification provides different kinds of health check procedures. Difference between them is only semantic. The nature of the procedure is defined by annotating the HealthCheck procedure with a specific annotation.

• Readiness checks defined with @Readiness annotation

• Liveness checks defined with @Liveness annotation

A HealthCheck procedure with none of the above annotations is not an active procedure and should be ignored.

Readiness check

A Health Check for readiness allows third party services to know if the application is ready to process requests or not.

The @Readiness annotation must be applied on a HealthCheck implementation to define a readiness check procedure, otherwise, this annotation is ignored.

Liveness check

A Health Check for liveness allows third party services to determine if the application is running. This means that if this procedure fails the application can be discarded (terminated, shutdown).

The @Liveness annotation must be applied on a HealthCheck implementation to define a Liveness check procedure, otherwise, this annotation is ignored.

Startup check

A Health check for startup allows applications to define startup probes that are used for initial verification of the application before the liveness probe takes over.

The @Startup annotation must be applied on a HealthCheck implementation to define a startup check procedure, otherwise, this annotation is ignored.

Integration with CDI

Any enabled bean with a bean of type org.eclipse.microprofile.health.HealthCheck and @Liveness, @Readiness, or @Startup qualifier can be used as health check procedure.

Contextual references of health check procedures are invoked by runtime when the outermost protocol entry point (i.e. http://HOST:PORT/health) receives an inbound request

@ApplicationScoped
@Liveness
@Readiness
public class MyCheck implements HealthCheck {

    public HealthCheckResponse call() {
        [...]
    }
}

Health check procedures are CDI beans, therefore, they can also be defined with CDI producers:

@ApplicationScoped
class MyChecks {

  @Produces
  @Liveness
  HealthCheck check1() {
    return () -> HealthCheckResponse.named("heap-memory").status(getMemUsage() < 0.9).build();
  }

  @Produces
  @Readiness
  HealthCheck check2() {
    return () -> HealthCheckResponse.named("cpu-usage").status(getCpuUsage() < 0.9).build();
  }

  @Produces
  @Startup
  HealthCheck check3() {
    return () -> HealthCheckResponse.named("initial-heap-memory").status(getMemUsage() < 0.95).build();
  }
}

SPI Usage

Implementors of the API are expected to supply implementations of HealthCheckResponse and HealthCheckResponseBuilder by providing a HealthCheckResponseProvider to their implementation. The HealthCheckResponseProvider is discovered using the default JDK service loader.

A HealthCheckResponseProvider is used internally to create a HealthCheckResponseBuilder which is used to construct a HealthCheckResponse. This pattern allows implementors to extend a HealthCheckResponse and adapt it to their implementation needs. Common implementation details that fall into this category are invocation and security contexts or anything else required to map a HealthCheckResponse to the outermost invocation protocol (i.e. HTTP/JSON).

Contributing

Do you want to contribute to this project? Find out how you can help here.