diff --git a/docs/se/health/01_health.adoc b/docs/se/health/01_health.adoc index 5f3e0bf8f34..8284ac8c152 100644 --- a/docs/se/health/01_health.adoc +++ b/docs/se/health/01_health.adoc @@ -20,6 +20,8 @@ :h1Prefix: SE :description: Helidon health checks :keywords: helidon, health-checks, health, check +:javadoc-base-url-api: {javadoc-base-url}io.helidon.health.checks/io/helidon/health/checks + This document describes the health check API available with Helidon SE. @@ -175,12 +177,37 @@ TIP: Balance collecting a lot of information with the need to avoid overloading === Built-in health-checks -A set of built-in health checks can be optionally enabled to report various - health check statuses that are commonly used: +You can use Helidon-provided health checks to report various + common health check statuses: + +[[built-in-health-checks-table]] +[cols="1,1,3,15,3"] +|======= +|Built-in health check |Health check name |JavaDoc |Config properties |Default config value + +|deadlock detection +|`deadlock` +| link:{javadoc-base-url-api}/DeadlockHealthCheck.html[`DeadlockHealthCheck`] +| n/a +| n/a + +|available disk space +|`diskSpace` +| link:{javadoc-base-url-api}/DiskSpaceHealthCheck.html[`DiskSpaceHealthCheck`] +|`helidon.healthCheck.diskSpace.thresholdPercent` + + + +`helidon.healthCheck.diskSpace.path` +| `99.999` + + + +`/` +|available heap memory +| `heapMemory` +| link:{javadoc-base-url-api}/HeapMemoryHealthCheck.html[`HeapMemoryHealthCheck`] +|`helidon.healthCheck.heapMemory.thresholdPercent` +|`98` +|======= -* deadlock detection -* available disk space -* available heap memory +The following code adds the default built-in health checks to your application: [source,java] ---- @@ -192,11 +219,26 @@ Routing.builder() .register(health) // <.> .build(); ---- -<.> Add built-in health checks (requires the `helidon-health-checks` +<.> 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 <> above. + +* Configure the behavior of the built-in health checks using the config property keys in the +<>. + +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 <>) you want to exclude. + +== Health report +Accessing the Helidon-provided `/health` endpoint reports the health of your application: [source,json] .JSON response. ---- @@ -236,6 +278,9 @@ Routing.builder() } ---- + + + === Strict JSON Output The JSON responses shown above contain properties `"status"` and `"outcome"` with the same diff --git a/health/health-checks/src/main/java/io/helidon/health/checks/DeadlockHealthCheck.java b/health/health-checks/src/main/java/io/helidon/health/checks/DeadlockHealthCheck.java index 6ebb2c09aca..7087c6713f6 100644 --- a/health/health-checks/src/main/java/io/helidon/health/checks/DeadlockHealthCheck.java +++ b/health/health-checks/src/main/java/io/helidon/health/checks/DeadlockHealthCheck.java @@ -32,9 +32,10 @@ /** * A health check that looks for thread deadlocks. Automatically created and registered via CDI. - * - * This health check can be referred to in properties as "deadlock". So for example, to exclude this - * health check from being exposed, use "helidon.health.exclude: deadlock". + *

+ * This health check can be referred to in properties as {@code deadlock}. So for example, to exclude this + * health check from being exposed, use {@code helidon.health.exclude: deadlock}. + *

*/ @Liveness @ApplicationScoped // this will be ignored if not within CDI diff --git a/health/health-checks/src/main/java/io/helidon/health/checks/DiskSpaceHealthCheck.java b/health/health-checks/src/main/java/io/helidon/health/checks/DiskSpaceHealthCheck.java index 687ed6fd904..e502d9e6496 100644 --- a/health/health-checks/src/main/java/io/helidon/health/checks/DiskSpaceHealthCheck.java +++ b/health/health-checks/src/main/java/io/helidon/health/checks/DiskSpaceHealthCheck.java @@ -40,20 +40,24 @@ * A health check that verifies whether the server is running out of disk space. This health check will * check whether the usage of the disk associated with a specific path exceeds a given threshold. If it does, * then the health check will fail. - * + *

* By default, this health check has a threshold of 100%, meaning that it will never fail the threshold check. - * Also, by defaut, it will check the root path "/". These defaults can be modified using the - * {@code healthCheck.diskSpace.path} property, and the {@code healthCheck.diskSpace.thresholdPercent} - * property. The threshold should be set to a fraction, such as .50 for 50% or .99 for 99%. If disk usage + * Also, by default, it will check the root path {@code /}. These defaults can be modified using the + * {@value CONFIG_KEY_PATH} property (default {@value DEFAULT_PATH}), and the {@value CONFIG_KEY_THRESHOLD_PERCENT} + * property (default {@value DEFAULT_THRESHOLD}, virtually 100). The threshold should be set to a percent, such as 50 for 50% or + * 99 for 99%. If disk usage * exceeds this threshold, then the health check will fail. - * + *

+ *

* Unless ephemeral disk space is being used, it is often not sufficient to simply restart a server in the event * that that health check fails. - * + *

* This health check is automatically created and registered through CDI. - * - * This health check can be referred to in properties as "diskSpace". So for example, to exclude this - * health check from being exposed, use "helidon.health.exclude: diskSpace". + *

+ *

+ * This health check can be referred to in properties as {@code diskSpace}. So for example, to exclude this + * health check from being exposed, use {@code helidon.health.exclude: diskSpace}. + *

*/ @Liveness @ApplicationScoped // this will be ignored if not within CDI diff --git a/health/health-checks/src/main/java/io/helidon/health/checks/HeapMemoryHealthCheck.java b/health/health-checks/src/main/java/io/helidon/health/checks/HeapMemoryHealthCheck.java index a9669d76594..6120411a060 100644 --- a/health/health-checks/src/main/java/io/helidon/health/checks/HeapMemoryHealthCheck.java +++ b/health/health-checks/src/main/java/io/helidon/health/checks/HeapMemoryHealthCheck.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2018, 2019 Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2018, 2020 Oracle and/or its affiliates. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -32,16 +32,20 @@ /** * A health check that verifies whether the server is running out of Java heap space. If heap usage exceeds a * specified threshold, then the health check will fail. - * - * By default, this health check has a threshold of .98 (98%). If heap usage exceeds this level, then the server + *

+ * By default, this health check has a threshold of {@value DEFAULT_THRESHOLD} ({@value DEFAULT_THRESHOLD}%). + * If heap usage exceeds this level, then the server * is considered to be unhealthy. This default can be modified using the - * {@code healthCheck.heapMemory.thresholdPercent} property. The threshold should be set to a fraction, such as - * .50 for 50% or .99 for 99%. - * + * {@value CONFIG_KEY_THRESHOLD_PERCENT} property. The threshold should be set as a percent, such as + * 50 for 50% or 99 for 99%. + *

+ *

* This health check is automatically created and registered through CDI. - * - * This health check can be referred to in properties as "heapMemory". So for example, to exclude this - * health check from being exposed, use "helidon.health.exclude: heapMemory". + *

+ *

+ * This health check can be referred to in properties as {@code heapMemory}. So for example, to exclude this + * health check from being exposed, use {@code helidon.health.exclude: heapMemory}. + *

*/ @Liveness @ApplicationScoped // this will be ignored if not within CDI @@ -52,6 +56,11 @@ public final class HeapMemoryHealthCheck implements HealthCheck { */ public static final double DEFAULT_THRESHOLD = 98; + /** + * Config property key for heap memory threshold. + */ + public static final String CONFIG_KEY_THRESHOLD_PERCENT = "helidon.health.heapMemory.thresholdPercent"; + private final Runtime rt; private final double thresholdPercent; @@ -59,7 +68,7 @@ public final class HeapMemoryHealthCheck implements HealthCheck { @Inject HeapMemoryHealthCheck( Runtime runtime, - @ConfigProperty(name = "helidon.health.heapMemory.thresholdPercent", defaultValue = "98") double threshold) { + @ConfigProperty(name = CONFIG_KEY_THRESHOLD_PERCENT, defaultValue = "98") double threshold) { this.thresholdPercent = threshold; this.rt = runtime; }