The health subsystem is part of the observability support. As a result, your application includes health support by default provided your project meets several conditions:

• Your project depends on the helidon-webserver-observe-health component as described above.

• (Optional) Your project depends on the helidon-health-checks component (if you want the built-in health checks).

• Your code allows the webserver’s automatic feature discovery (enabled by default).

• Your code allows the observe feature’s automatic observer discovery (also enabled by default).

If you disable either type of automatic discovery you can add the observe feature to the webserver explicitly, and you can add the health observer to the observe feature explicitly, customizing the behavior of each programmatically if you wish. You can also use configuration to tailor some of the behavior of the health component (such as changing the URI path from /observe/health to something else).

In many cases, the ability of your application to do its job depends on conditions known only to your application: for example, whether certain external resources such as databases are available. You can create custom health checks which reflect those conditions and add them to the overall health assessment of your application.

A health check is a Java functional interface that returns a new HealthCheckResponse instance each time Helidon queries the health check. Each health check also has a fixed name and a fixed health check type (start-up, liveness, or readiness).

Your code registers a custom health check by invoking a method on Helidon-provided types in one of the following ways:

• Pass the name and type of the health check and a Supplier of a HealthCheckResponse such as a method reference or a lambda expression.

• Pass an instance of a class which implements the HealthCheck interface.

Within an application different techniques might make sense for different custom health checks, depending on the complexity of the logic for computing the status for each check. The various styles are functionally equivalent; for a given custom health check choose the style which enhances the readability and clarity of your code. The examples below, in no particular order, implement the same custom health check functionality in different ways to illustrate.

Option 1: Using a HealthCheckResponse supplier method

static HealthCheckResponse slowStartLivenessResponse() {
    long now = System.currentTimeMillis();
    return HealthCheckResponse.builder()
            .detail("time", now)
            .status(now - serverStartTime >= 8000)
            .build();
}

ObserveFeature observe = ObserveFeature.builder()
        .config(config.get("server.features.observe")) 
        .addObserver(HealthObserver.builder() 
                             .useSystemServices(true) 
                             .addCheck(Main::slowStartLivenessResponse, 
                                       HealthCheckType.LIVENESS, 
                                       "live-after-8-seconds") 
                             .build())
        .build();

Option 2: Using an in-line lambda expression

ObserveFeature observe = ObserveFeature.builder()
        .config(config.get("server.features.observe"))
        .addObserver(HealthObserver.builder() 
                             .useSystemServices(true) // Include Helidon-provided health checks.
                             .addCheck(() -> HealthCheckResponse.builder() 
                                               .status(System.currentTimeMillis() - serverStartTime >= 8000) 
                                               .detail("time", System.currentTimeMillis()) 
                                               .build(), 
                                       HealthCheckType.READINESS, 
                                       "live-after-8-seconds") 
                             .build())
        .build();

Option 3: Using a HealthCheck Instance

/**
 * A custom readiness health check that reports UP 8 seconds after server start-up.
 */
class SlowStartHealthCheck implements HealthCheck { 

    @Override
    public HealthCheckType type() {
        return HealthCheckType.READINESS; 
    }

    @Override
    public HealthCheckResponse call() {
        long now = System.currentTimeMillis();
        return HealthCheckResponse.builder()
                .detail("time", now) 
                .status(now - serverStartTime >= 8000) 
                .build();
    }
}

ObserveFeature observe = ObserveFeature.builder()
        .config(config.get("server.features.observe"))
        .addObserver(HealthObserver.builder() 
                             .addCheck(new SlowStartHealthCheck()) 
                             .build())
        .build();

Adding Observability (including the Custom Health Checks) to Helidon

WebServer server = WebServer.builder()
        .featuresDiscoverServices(false)
        .addFeature(observe) 
        .routing(Main::routing)
        .build()
        .start();

Triggering and Interpreting Health Check Output

{
  "status": "DOWN",
  "checks": [
    {
      "name": "live-after-8-seconds",
      "status": "DOWN",
      "data": {
        "time": 1701984253071
      }
    }
  ]
}

{
  "status": "UP",
  "checks": [
    {
      "name": "live-after-8-seconds",
      "status": "UP",
      "data": {
        "time": 1701984258292
      }
    }
  ]
}

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

† Helidon cannot support the indicated health checks in the GraalVM native image environment, so with native image those health checks do not appear in the health output.

Simply adding the built-in health check dependency is sufficient to register all the built-in health checks automatically. If you want to use only some of the built-in checks in your application, you can disable automatic discovery of the built-in health checks and register only the ones you want.

The following code adds only selected built-in health checks to your application:

WebServer server = WebServer.builder()
        .config(config.get("server"))
        .addFeature(ObserveFeature.create(HealthObserver.builder()
                                                  .useSystemServices(false) 
                                                  .addCheck(HealthChecks.deadlockCheck()) 
                                                  .addCheck(hc) 
                                                  .details(true)
                                                  .build()))
        .routing(Main::routing)
        .build()
        .start();

• Disables automatic registration of the built-in health checks.
• Adds the specific built-in check(s) you want.
• Adds a custom check (in a previously-prepared variable hc).

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.

• Using configuration as explained in Configuration.

• Liveness Probe

• Readiness Probe

• Startup Probe

Probes is the term used by Kubernetes to describe health checks for containers (Kubernetes documentation).

There are three types of probes:

• liveness: Indicates whether the container is running

• readiness: Indicates whether the container is ready to service requests

• startup: Indicates whether the application in the container has started

You can implement probes using the following mechanisms:

1. Running a command inside a container
2. Sending an HTTP request to a container
3. Opening a TCP socket to a container

A microservice exposed to HTTP traffic will typically implement both the liveness probe and the readiness probe using HTTP requests. If the microservice takes a significant time to initialize itself, you can also define a startup probe, in which case Kubernetes does not check liveness or readiness probes until the startup probe returns success.

You can configure several parameters for probes. The following are the most relevant parameters:

Liveness Probe

Readiness Probe

Startup Probe

Failed probes are recorded as events associated with their corresponding pods. The event message contains only the status code.

POD_NAME=$(kubectl get pod -l app=acme -o jsonpath='{.items[0].metadata.name}') 
kubectl get event --field-selector involvedObject.name=${POD_NAME} 

• Get the effective pod name by filtering pods with the label app=acme.
• Filter the events for the pod.

Accessing the Helidon-provided /observe/health endpoint reports the health of your application as shown below:

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

This example shows the usage of the Helidon health API in an application that implements health endpoints for the liveness and readiness probes. Note that the application code dissociates the health endpoints from the default routes, so that the health endpoints are not exposed by the service. An example YAML specification is also provided for the Kubernetes service and deployment.

ObserveFeature observeFeature = ObserveFeature.builder()
        .addObserver(HealthObserver.builder()
                             .useSystemServices(false)
                             .endpoint("/health/live") 
                             .addChecks(HealthChecks.healthChecks()) 
                             .build())
        .addObserver(HealthObserver.builder()
                             .useSystemServices(false)
                             .endpoint("/health/ready") 
                             .addCheck(() -> HealthCheckResponse.builder() 
                                               .status(true)
                                               .build(),
                                       HealthCheckType.READINESS,
                                       "database")
                             .build())
        .sockets(List.of("observe")) 
        .build();
WebServer server = WebServer.builder()
        .putSocket("@default", socket -> socket
                .port(8080) 
                .routing(r -> r.any((req, res) -> res.send("It works!")))) 
        .addFeature(observeFeature)
        .putSocket("observe", socket -> socket
                .port(8081)) 
        .build()
        .start();

• The health service for the liveness probe is exposed at /health/live.
• Using the built-in health checks for the liveness probe.
• The health service for the readiness probe is exposed at /health/ready.
• Using a custom health check for a pseudo database that is always UP.
• Route the observe feature exclusively on the observe socket.
• The default socket uses port 8080 for the default routes.
• The default route: returns It works! for any request.
• The observe socket uses port 8081 for the "/observe" routes.

kind: Service
apiVersion: v1
metadata:
  name: acme 
  labels:
    app: acme
spec:
  type: NodePort
  selector:
    app: acme
  ports:
  - port: 8080
    targetPort: 8080
    name: http
---
kind: Deployment
apiVersion: apps/v1
metadata:
  name: acme 
spec:
  replicas: 1
  selector:
    matchLabels:
      app: acme
  template:
    metadata:
      name: acme
      labels:
        name: acme
    spec:
      containers:
      - name: acme
        image: acme
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8080
        livenessProbe:
          httpGet:
            path: /observe/health/live 
            port: 8081
          initialDelaySeconds: 3 
          periodSeconds: 10
          timeoutSeconds: 3
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /observe/health/ready 
            port: 8081
          initialDelaySeconds: 10 
          periodSeconds: 30
          timeoutSeconds: 10
---

• A service of type NodePort that serves the default routes on port 8080.
• A deployment with one replica of a pod.
• The HTTP endpoint for the liveness probe.
• The liveness probe configuration.
• The HTTP endpoint for the readiness probe.
• The readiness probe configuration.