Maven Coordinates
To enable MicroProfile Health either add a dependency on the helidon-microprofile bundle or add the following dependency to your project’s pom.xml (see Managing Dependencies).
<dependency>
<groupId>io.helidon.microprofile.health</groupId>
<artifactId>helidon-microprofile-health</artifactId>
</dependency>To enable built-in health checks add the following dependency (or use the helidon-microprofile bundle )
<dependency>
<groupId>io.helidon.health</groupId>
<artifactId>helidon-health-checks</artifactId>
</dependency>Overview
Microservices expose their health status primarily so external tools (for example, an orchestrator such as Kubernetes) can monitor each service and take action, such as restarting a service instance if it has failed or temporarily shunting traffic away from the instance if the service is unable to process incoming requests normally.
About the MicroProfile Health Specification
Helidon MP implements the MicroProfile Health spec. The spec prescribes how external tools probe a service’s health checks and how you implement health checks as part of your microservice that are specific to your service’s needs.
Concepts
Liveness and Readiness Checks
MicroProfile Health supports two types of health checks:
Liveness checks report whether the runtime environment in which the service is running is sufficient to support the work the service performs. The environment is beyond the control of the service itself and typically cannot improve without outside intervention. If a microservice instance reports a DOWN liveness check, it should never report UP later. It will need to be stopped and a replacement instance created.
Readiness checks report whether the service is currently capable of performing its work. A service that reports DOWN for its readiness cannot at the moment do its job, but at some future point it might become able to do so without requiring a restart.
The following table describes more about these two types of health checks, including how an orchestrator such as Kubernetes might react.
Known Health Check Endpoints
A MicroProfile-compliant service reports its health via known REST endpoints. Helidon MP provides these endpoints automatically as part of every MP microservice.
External management tools (or curl or browsers) retrieve liveness via /health/live and readiness via /health/ready.
Responses from the health endpoints report 200 (OK), 204 (no content), or 503 (service unavailable) depending on the outcome of running the health checks. HTTP GET responses include JSON content showing the detailed results of all the health checks which the server executed after receiving the request. HTTP HEAD requests return only the status with no payload.
The following table summarizes the two types of health checks in MicroProfile Health.
| Type | Meaning | REST endpoint | Kubernetes response on failure |
|---|---|---|---|
| liveness | whether the runtime environment is suitable | /health/live | Restarts container. |
| readiness | whether the microservice is currently capable of doing its work | /health/ready | Diverts requests away from the instance; periodically rechecks readiness and resumes traffic once the microservice reports itself as ready. |
Built-in and Custom Health Checks
Built-in Health Checks
Helidon provides built-in, default checks for each endpoint. The built-in liveness checks include various environmental values, such as whether the JVM has detected deadlocks or whether there is sufficient heap space. The built-in readiness check always reports UP.
You can see all the defaults by accessing any Helidon MP microservice’s /health/live endpoint and viewing the response.
Custom Health Checks
Add your own liveness or readiness checks by adding a Java class for each check. Each custom check must implement the HealthCheck interface, and you add either the @Liveness or the @Readiness annotation to the class.
Next Steps
Add custom health checks to your own microservices.
The Helidon MP Health Check Guide shows how to create a sample project and add custom liveness and readiness health checks.