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.
The proposed solution breaks down into two parts:
-
A health check protocol and wireformat
-
A Java API to implement health check procedures
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.
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;
[...]
}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");
}
}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.
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.
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.
Any enabled bean with a bean of type org.eclipse.microprofile.health.HealthCheck and @Liveness or @Readiness 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();
}
}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).
Do you want to contribute to this project? Find out how you can help here.