Health Checks

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

Maven Coordinates

To enable Health Checks add the following dependency to your project’s pom.xml (see Managing Dependencies).

<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

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

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 (with health check details in the response).
`204`	The application is healthy (with no health check details in the response).
`503`	The application is not healthy.
`500`	An error occurred while reporting the health.

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.

Create the health support service:

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

Copied

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

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

Copied

Add a custom health check. This example returns UP and current time.
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(health) 
        .build();

Copied

Add built-in health checks using defaults (requires the helidon-health-checks dependency).
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.