Helidon SE Helpings: Show Details For Health Endpoint

With Helidon SE you can add a health endpoint to your application by simply adding a dependency. In your pom.xml you have to add the dependency io.helidon.webserver.observe:helidon-webserver-observe-health. This adds a new endpoint /health to your application. When your application is up and running the /health endpoint will return the HTTP status code 204 with an empty body. If your application is not healthy then the HTTP status code 503 is returned. In case of an error an HTTP status code 500 is sent to the client.

If you want to see a response with details then you need to set the configuration property server.features.observe.observers.health.details to the value true. Instead of the HTTP status code 204 the status code 200 is returned when our application is healthy. The response contains a JSON object with a status field with the value UP for a healthy response. The response also contains the field checks with an array of detailed information from health checks that are available in our application.

In the following example application you add a health endpoint with details. First you add the dependency to the pom.xml file:

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

Next you can start the application to try out the health endpoint. Using a HTTP client, for example curl, you can send a GET request to the health endpoint:

$ curl -X GET -i "http://localhost:8080/observe/health"
HTTP/1.1 204 No Content
Date: Fri, 24 Jan 2025 15:55:06 +0100
Connection: keep-alive
Content-Length: 0

You see that the HTTP status code 204 is returned.

In order to see some more details you need to set the configuration property server.features.observe.observers.health.details to the value true. Depending on the configuration file format that is supported you add this property to a configuration file. If you use application.properties simply add the following line:

...
server.features.observe.observers.health.details=true
...

Alternatively you can also set the property value using Java system properties or environment variables.

You need to read in the configuration and use it configure the WebServer instance:

import io.helidon.webserver.WebServer;
import io.helidon.config.Config;
...
    Config config = Config.create();
    Config.global(config);

    WebServer server =
        WebServer.builder()
            .config(config.get("server"))
            .build()
            .start();
...

Now you can send a GET request to the health endpoint again:

$ curl -X GET -i "http://localhost:8080/observe/health"
HTTP/1.1 200 OK
Date: Fri, 24 Jan 2025 15:57:35 +0100
Connection: keep-alive
Content-Length: 27
Content-Type: application/json

{"status":"UP","checks":[]}

The application doesn’t have any extra health checks so the checks array is empty. You can also see the HTTP status code 200 is returned and the response contains a JSON object with the field status with the value UP.

You can also use Java code to add a detailed health check. In the following example we add a feature to our code that creates the WebServer instance:

import io.helidon.webserver.WebServer;
import io.helidon.config.Config;
...
    Config config = Config.create();
    Config.global(config);

    WebServer server =
        WebServer.builder()
            .addFeature(
                ObserveFeature.builder()
                    // Add health observer with details
                    .addObserver(HealthObserver.builder().details(true).build())
                    .build())
            // Allow override of configuration properties
            .config(config.get("server"))
            .build()
            .start();
...

Written with Helidon 4.1.6.