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.
Help optimize Enterprise Java for a microservices architecture.
Join the MicroProfile Google Group, peruse recent topics or create your own, and join in on the conversation. It's that easy!
JOIN THE DISCUSSION