Once your application is deployed to production you want to ensure it's up– and running. To determine the health and status of your application you can use monitoring based on different metrics, but this requires further knowledge and takes time. Usually, you just want a quick answer to the question: Is my application up? The same is true if your application is running e.g. in a Kubernetes cluster, where the cluster regularly performs health probes to terminate unhealthy pods. With MicroProfile Health you can write both readiness and liveness checks and expose them via an HTTP endpoint with ease.
Learn more about the MicroProfile Health specification and how to use it in this blog post.
Specification profile: MicroProfile Health
- Current version: 2.2 in MicroProfile
- GitHub repository
- Latest specification document
- Basic use case: Add liveness and readiness checks to determine the application's health
Determine the application's health with MicroProfile Health
With MicroProfile Health you get three new endpoints to determine both the readiness and liveness of your application:
/health/ready: Returns the result of all readiness checks and determines whether or not your application can process requests/health/live: Returns the result of all liveness checks and determines whether or not your application is up- and running/health: As in previous versions of MicroProfile Health there was no distinction between readiness and liveness, this is active for downwards compatibility. This endpoint returns the result of both health check types.
To determine your readiness and liveness you can have multiple checks. The overall status is constructed with a logical AND of all your checks of that specific type (liveness or readiness). If e.g. on liveness check fails, the overall liveness status is DOWN and the HTTP status is 503:
| 1 2 3 4 5 6 7 8 9 | $ curl -v http://localhost:9080/health/live < HTTP/1.1 503 Service Unavailable < X-Powered-By: Servlet/4.0 < Content-Type: application/json; charset=UTF-8 < Content-Language: en-US {"checks":[...],"status":"DOWN"} |
In case of an overall UP status, you'll receive the HTTP status 200:
| 1 2 3 4 5 6 7 8 | $ curl -v http://localhost:9080/health/ready < HTTP/1.1 200 OK < X-Powered-By: Servlet/4.0 < Content-Type: application/json; charset=UTF-8 < Content-Language: en-US {"checks":[...],"status":"UP"} |
Create a readiness check
To create a readiness check you have to implement the HealthCheck interface and add @Readiness to your class:
| 1 2 3 4 5 6 7 8 9 10 11 | @Readiness public class ReadinessCheck implements HealthCheck { @Override public HealthCheckResponse call() { return HealthCheckResponse.builder() .name("readiness") .up() .build(); } } |
As you can add multiple checks, you need to give every check a dedicated name. In general, all your readiness checks should determine whether your application is ready to accept traffic or not. Therefore a quick response is preferable.
If your application is about exposing and accepting data using REST endpoints and does not rely on other services to work, the readiness check above should be good enough as it returns 200 once the JAX-RS runtime is up- and running:
| 1 2 3 4 5 6 7 8 9 10 | { "checks":[ { "data":{}, "name":"readiness", "status":"UP" } ], "status":"UP" } |
Furthermore, once /health/ready returns 200, the readiness is identified and from now on the /health/live is used and no more readiness checks are required.
Create liveness checks
Creating liveness checks is as simple as creating readiness checks. The only difference is the @Livness annotation at class level:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | @Liveness public class DiskSizeCheck implements HealthCheck { @Override public HealthCheckResponse call() { File file = new File("/"); long freeSpace = file.getFreeSpace() / 1024 / 1024; return responseBuilder = HealthCheckResponse.builder() .name("disk") .withData("remainingSpace", freeSpace) .state(freeSpace > 100) .build(); } |
In this example, I'm checking for free disk space as a service might rely on storage to persist e.g. files. With the .withData() method of the HealthCheckResponseBuilder you can add further metadata to your response.
In addition, you can also combine the @Readiness and @Liveness annotation and reuse a health check class for both checks:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | @Readiness @Liveness public class MultipleHealthCheck implements HealthCheck { @Override public HealthCheckResponse call() { return HealthCheckResponse .builder() .name("generalCheck") .withData("foo", "bar") .withData("uptime", 42) .withData("isReady", true) .up() .build(); } } |
This check now appears for /health/ready and /health/live:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "checks":[ { "data":{ "remainingSpace":447522 }, "name":"disk", "status":"UP" }, { "data":{ }, "name":"liveness", "status":"UP" }, { "data":{ "foo":"bar", "isReady":true, "uptime":42 }, "name":"generalCheck", "status":"UP" } ], "status":"UP" } |
Other possible liveness checks might be: checking for active JDBC connections, connections to queues, CPU usage, or custom metrics (with the help of MicroProfile Metrics).
YouTube video for using MicroProfile Health
Watch the following YouTube video of my Getting started with MicroProfile series to see MicroProfile Health in action:
You can find the source code for this blog post on GitHub.
Have fun using MicroProfile Health,
Phil
