Health Checks

Health Checks: This document describes the health check API available with Helidon SE.

About health checks

It’s a good practice to monitor your microservice’s health, to ensure that it is available and performs correctly.

Applications implement health checks to expose health status that is collected at regular intervals by external tooling, such as orchestrators like Kubernetes. The orchestrator may then take action, such as restarting your application if the health check fails.

A typical health check combines the statuses of all the dependencies that affect availability and the ability to perform correctly:

network latency
storage
database
other services used by your application

Prerequisites

Declare the following dependency in your project:

<dependency>
    <groupId>io.helidon.health</groupId>
    <artifactId>helidon-health</artifactId>
</dependency>

Copied

Optional dependency to use built-in health checks:

<dependency>
    <groupId>io.helidon.health</groupId>
    <artifactId>helidon-health-checks</artifactId>
</dependency>

Copied

API overview

Health check API classes

`org.eclipse.microprofile.health.HealthCheck`	Java functional interface representing the logic of a single health check
`org.eclipse.microprofile.health.HealthCheckResponse`	Result of a health check invocation that contains a state and a description.
`org.eclipse.microprofile.health.HealthCheckResponseBuilder`	Builder class to create `HealthCheckResponse` instances
`io.helidon.health.HealthSupport`	WebServer service that exposes `/health` and invokes the registered health checks
`io.helidon.health.HealthSupport.Builder`	Builder class to create `HealthSupport` instances

A health check is a Java functional interface that returns a HealthCheckResponse object. You can choose to implement a health check inline with a lambda expression or you can reference a method with the double colon operator ::.

Health check with a lambda expression:

HealthCheck hc = () -> HealthCheckResponse
        .named("exampleHealthCheck")
        .up()
        .build();

Copied

Health check with method reference:

HealthCheckResponse exampleHealthCheck(){
    return HealthCheckResponse
        .named("exampleHealthCheck")
        .up()
        .build();
}
HealthCheck hc = this::exampleHealthCheck;

Copied

HealthSupport is a WebServer service that contains a collection of registered HealthCheck instances. When queried, it invokes the registered health check and returns a response with a status code representing the overall state of the application.

Health status codes

`200`	The application is healthy.
`503`	The application is not healthy.
`500`	An error occurred while reporting the health.

The HTTP response also contains a JSON payload that describes the statuses for all health checks.

Create the health support service:

HealthSupport health = HealthSupport.builder()
    .addLiveness(hc)
    .build();

Copied

Health check requires the JSON-P support to be enabled. See the example below.

Example

HealthSupport health = HealthSupport.builder()
    .addLiveness(() -> HealthCheckResponse.named("exampleHealthCheck")
                 .up()
                 .withData("time", System.currentTimeMillis())
                 .build()) 
    .build();

Routing.builder()
        .register(JsonSupport.create()) 
        .register(health) 
        .build();

Copied

Add a custom health check. This example returns UP and current time.
Enable support for JSON.
Register health support with web server routing (adds the /health endpoint).

Balance collecting a lot of information with the need to avoid overloading the application and overwhelming users.

JSON response:

{
    "outcome": "UP",
    "status": "UP",
    "checks": [
        {
            "name": "exampleHealthCheck",
            "state": "UP",
            "data": {
                "time": 1546958376613
            }
        }
    ]
}

Copied

Built-in health-checks

You can use Helidon-provided health checks to report various common health check statuses:

Built-in health check	Health check name	JavaDoc	Config properties	Default config value
deadlock detection	`deadlock`	`DeadlockHealthCheck`	n/a	n/a
available disk space	`diskSpace`	`DiskSpaceHealthCheck`	`helidon.healthCheck.diskSpace.thresholdPercent` `helidon.healthCheck.diskSpace.path`	`99.999` `/`
available heap memory	`heapMemory`	`HeapMemoryHealthCheck`	`helidon.healthCheck.heapMemory.thresholdPercent`	`98`

The following code adds the default built-in health checks to your application:

HealthSupport health = HealthSupport.builder()
    .addLiveness(HealthChecks.healthChecks()) 
    .build();

Routing.builder()
        .register(JsonSupport.create()) 
        .register(health) 
        .build();

Copied

Add built-in health checks using defaults (requires the helidon-health-checks dependency).
Register the JSON-P support in the web server routing.
Register the created health support with web server routing (adds the /health endpoint).

You can control the thresholds for built-in health checks in either of two ways:

Create the health checks individually using their builders instead of using the HealthChecks convenience class. Follow the JavaDoc links in the table above.
Configure the behavior of the built-in health checks using the config property keys in the table.

Further, you can suppress one or more of the built-in health checks by setting the configuration item helidon.health.exclude to a comma-separated list of the health check names (from the table) you want to exclude.

Health report

Accessing the Helidon-provided /health endpoint reports the health of your application:

JSON response.

{
    "outcome": "UP",
    "status": "UP",
    "checks": [
        {
            "name": "deadlock",
            "state": "UP"
        },
        {
            "name": "diskSpace",
            "state": "UP",
            "data": {
                "free": "211.00 GB",
                "freeBytes": 226563444736,
                "percentFree": "45.31%",
                "total": "465.72 GB",
                "totalBytes": 500068036608
            }
        },
        {
            "name": "heapMemory",
            "state": "UP",
            "data": {
                "free": "215.15 MB",
                "freeBytes": 225600496,
                "max": "3.56 GB",
                "maxBytes": 3817865216,
                "percentFree": "99.17%",
                "total": "245.50 MB",
                "totalBytes": 257425408
            }
        }
    ]
}

Copied

Strict JSON Output

The JSON responses shown above contain properties "status" and "outcome" with the same values. Helidon reports both of these to maintain backward compatibility with older versions of MicroProfile Health. This behavior can be disabled by setting the property health.backward-compatible to false, in which case only "status" is reported. Future versions of Helidon will drop support for older versions of Health, so it is recommended to rely on "status" instead of "outcome" in your applications.