Improve doc for built-in health check thresholds, etc. (#2559)

* Improve doc for built-in health check thresholds, etc.

Signed-off-by: tim.quinn@oracle.com <tim.quinn@oracle.com>

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 <<built-in-health-checks-table,table>> above.
+
+* Configure the behavior of the built-in health checks using the config property keys in the
+<<built-in-health-checks-table,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 <<built-in-health-checks-table,table>>) 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

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".
+ * <p>
+ * 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}.
+ * </p>
  */
 @Liveness
 @ApplicationScoped // this will be ignored if not within CDI

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.
- *
+ * <p>
  * 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.
- *
+ * </p>
+ * <p>
  * 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.
- *
+ *<p>
  * 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".
+ *</p>
+ * <p>
+ * 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}.
+ * </p>
  */
 @Liveness
 @ApplicationScoped // this will be ignored if not within CDI

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
+ * <p>
+ * 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%.
+ * </p>
+ * <p>
  * 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".
+ * </p>
+ * <p>
+ * 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}.
+ * </p>
  */
 @Liveness
 @ApplicationScoped // this will be ignored if not within CDI
@@ -52,14 +56,19 @@ 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;
 
     // this will be ignored if not within CDI
     @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;
     }