MicroProfile Health supports three types of health checks:

• Liveness checks report whether the runtime environment in which the service is running is sufficient to support the work the service performs. The environment is beyond the control of the service itself and typically cannot improve without outside intervention. If a microservice instance reports a DOWN liveness check, it should never report UP later. It will need to be stopped and a replacement instance created.

• Readiness checks report whether the service is currently capable of performing its work. A service that reports DOWN for its readiness cannot at the moment do its job, but at some future point it might become able to do so without requiring a restart.

• Startup checks indicate whether the service has started to the point where liveness and readiness checks even make sense. A service reporting DOWN for a startup check is still initializing itself and normally will report UP soon, assuming it is able to start successfully.

Properties may be set in application.yaml or in microprofile-config.properties, in both cases using the health prefix.

For example, you can specify a custom port and root context for the root health endpoint path. However, you cannot use different ports, such as http://localhost:8080/myhealth and http://localhost:8081/myhealth/live. Likewise, you cannot use different paths, such as http://localhost:8080/health and http://localhost:8080/probe/live. The example below will change the root path.

health.endpoint=/myhealth  

• The endpoint setting specifies the root path for the health endpoint.

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.

By setting the config properties listed in the table you can influence the behavior of the health checks.

Further, you can suppress one or more health checks by setting the configuration item server.features.observe.observers.health.exclude to a comma-separated list of the health check names you want to exclude. The table above lists the names for the built-in health checks.

Helidon has a set of built-in health checks that can report various conditions:

• deadlock detection

• available disk space

• available heap memory

The following example will demonstrate how to use the built-in health checks. These examples are all executed from the root directory of your project (helidon-quickstart-mp).

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

mvn package
java -jar target/helidon-quickstart-mp.jar

curl http://localhost:8080/health

{
  "status": "UP",
  "checks": [
    {
      "name": "deadlock",
      "status": "UP"
    },
    {
      "name": "diskSpace",
      "status": "UP",
      "data": {
        "free": "325.54 GB",
        "freeBytes": 349543358464,
        "percentFree": "69.91%",
        "total": "465.63 GB",
        "totalBytes": 499963174912
      }
    },
    {
      "name": "heapMemory",
      "status": "UP",
      "data": {
        "free": "230.87 MB",
        "freeBytes": 242085696,
        "max": "3.56 GB",
        "maxBytes": 3817865216,
        "percentFree": "98.90%",
        "total": "271.00 MB",
        "totalBytes": 284164096
      }
    }
  ]
}

You can create application-specific custom health checks and integrate them with Helidon using CDI. The following example shows how to add a custom liveness health check.

@Liveness 
@ApplicationScoped 
public class GreetLivenessCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("LivenessCheck")  
                .up()
                .withData("time", System.currentTimeMillis())
                .build();
    }
}

• Annotation indicating this is a liveness health check.
• Annotation indicating this is a bean instantiated once per application (in Helidon this means just once per runtime).
• Build the HealthCheckResponse with status UP and the current time.

curl http://localhost:8080/health/live

{
  "status": "UP",
  "checks": [
    {
      "name": "LivenessCheck",
      "status": "UP",
      "data": {
        "time": 1566338255331
      }
    }
  ]
}

You can add a readiness check to indicate that the application is ready to be used. In this example, the server will wait five seconds before it becomes ready.

@Readiness 
@ApplicationScoped
public class GreetReadinessCheck implements HealthCheck {
    private final AtomicLong readyTime = new AtomicLong(0);

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("ReadinessCheck")  
                .status(isReady())
                .withData("time", readyTime.get())
                .build();
    }

    public void onStartUp(
            @Observes @Initialized(ApplicationScoped.class) Object init) {
        readyTime.set(System.currentTimeMillis()); 
    }

    private boolean isReady() { 
        return Duration.ofMillis(System.currentTimeMillis() - readyTime.get()).getSeconds() >= 5;
    }
}

• Annotation indicating that this is a readiness health check.
• Build the HealthCheckResponse with status UP after five seconds, else DOWN.
• Record the time at startup.
• Become ready after 5 seconds.

curl -v  http://localhost:8080/health/ready

< HTTP/1.1 503 Service Unavailable 

• The HTTP status is 503 since the application is not ready.

{
  "status": "DOWN",
  "checks": [
    {
      "name": "ReadinessCheck",
      "status": "DOWN",
      "data": {
        "time": 1566399775700
      }
    }
  ]
}

curl -v http://localhost:8080/health/ready

< HTTP/1.1 200 OK 

• The HTTP status is 200 indicating that the application is ready.

{
  "status": "UP",
  "checks": [
    {
      "name": "ReadinessCheck",
      "status": "UP",
      "data": {
        "time": 1566399775700
      }
    }
  ]
}

Full example code is available here.

You can add a startup check to indicate whether or not the application has initialized to the point that the other health checks make sense. In this example, the server will wait eight seconds before it declares itself started.

@Startup 
@ApplicationScoped
public class GreetStartedCheck implements HealthCheck {
    private final AtomicLong readyTime = new AtomicLong(0);

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("StartedCheck")  
                .status(isStarted())
                .withData("time", readyTime.get())
                .build();
    }

    public void onStartUp(
            @Observes @Initialized(ApplicationScoped.class) Object init) {
        readyTime.set(System.currentTimeMillis()); 
    }

    private boolean isStarted() { 
        return Duration.ofMillis(System.currentTimeMillis() - readyTime.get()).getSeconds() >= 8;
    }
}

• Annotation indicating that this is a startup health check.
• Build the HealthCheckResponse with status UP after eight seconds, else DOWN.
• Record the time at startup of Helidon; the application will declare itself as started eight seconds later.
• Become ready after 5 seconds.

curl -v  http://localhost:8080/health/started

< HTTP/1.1 503 Service Unavailable 

• The HTTP status is 503 since the application has not started.

{
  "status": "DOWN",
  "checks": [
    {
      "name": "StartedCheck",
      "status": "DOWN",
      "data": {
        "time": 1566399775700
      }
    }
  ]
}

curl -v http://localhost:8080/health/started

< HTTP/1.1 200 OK 

• The HTTP status is 200 indicating that the application is started.

{
  "status": "UP",
  "checks": [
    {
      "name": "StartedCheck",
      "status": "UP",
      "data": {
        "time": 1566399775700
      }
    }
  ]
}

When using the health check URLs, you can get the following health check data:

• liveness only - http://localhost:8080/health/live

• readiness only - http://localhost:8080/health/ready

• startup checks only - http://localhost:8080/health/started

• all health check data - http://localhost:8080/health

curl http://localhost:8080/health

{
  "status": "UP",
  "checks": [
    {
      "name": "LivenessCheck",
      "status": "UP",
      "data": {
        "time": 1566403431536
      }
    }
  ]
}

Full example code is available here.