From 87ebf81422d745875b9bc6b26bfb4bc77ba483d8 Mon Sep 17 00:00:00 2001
From: "tim.quinn@oracle.com"
Date: Tue, 1 Dec 2020 20:54:38 -0600
Subject: [PATCH 1/4] Improve doc for built-in health check thresholds, etc.
Signed-off-by: tim.quinn@oracle.com
---
docs/se/health/01_health.adoc | 52 ++++++++++++++++---
.../health/checks/DeadlockHealthCheck.java | 7 +--
.../health/checks/DiskSpaceHealthCheck.java | 22 ++++----
.../health/checks/HeapMemoryHealthCheck.java | 26 ++++++----
4 files changed, 79 insertions(+), 28 deletions(-)
diff --git a/docs/se/health/01_health.adoc b/docs/se/health/01_health.adoc
index 5f3e0bf8f34..e0a6e2f6a21 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,32 @@ 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,20"]
+|=======
+|Built-in health check |Health check name |JavaDoc |Config properties [default value]
+
+|deadlock detection
+|`deadlock`
+| link:{javadoc-base-url-api}/DeadlockHealthCheck.html[`DeadlockHealthCheck`]
+| n/a
+
+|available disk space
+|`diskSpace`
+| link:{javadoc-base-url-api}/DiskSpaceHealthCheck.html[`DiskSpaceHealthCheck`]
+|`helidon.healthCheck.diskSpace.thresholdPercent` [`99.999`] +
+ +
+`helidon.healthCheck.diskSpace.path` [`/`]
+|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]
----
@@ -193,10 +215,25 @@ Routing.builder()
.build();
----
<.> Add built-in health checks (requires the `helidon-health-checks`
- dependency).
+ dependency) using defaults.
<.> 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 +273,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..07812cf0a94 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%. The default is .
+ *
+ *
* 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,8 @@ public final class HeapMemoryHealthCheck implements HealthCheck {
*/
public static final double DEFAULT_THRESHOLD = 98;
+ public static final String CONFIG_KEY_THRESHOLD_PERCENT = "helidon.health.heapMemory.thresholdPercent";
+
private final Runtime rt;
private final double thresholdPercent;
@@ -59,7 +65,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;
}
From 5cfbd318538bf91f5ed2dd4bd054fb8b8e549c80 Mon Sep 17 00:00:00 2001
From: "tim.quinn@oracle.com"
Date: Tue, 1 Dec 2020 21:13:45 -0600
Subject: [PATCH 2/4] Add JavaDoc for new constant
---
.../java/io/helidon/health/checks/HeapMemoryHealthCheck.java | 3 +++
1 file changed, 3 insertions(+)
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 07812cf0a94..bf2270e2680 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
@@ -56,6 +56,9 @@ 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;
From 7f58a5b9b491a6177539813457ad8233c8490114 Mon Sep 17 00:00:00 2001
From: "tim.quinn@oracle.com"
Date: Wed, 2 Dec 2020 09:08:33 -0600
Subject: [PATCH 3/4] Remove a content-free sentence fragment
---
.../java/io/helidon/health/checks/HeapMemoryHealthCheck.java | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
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 bf2270e2680..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
@@ -37,7 +37,7 @@
* If heap usage exceeds this level, then the server
* is considered to be unhealthy. This default can be modified using the
* {@value CONFIG_KEY_THRESHOLD_PERCENT} property. The threshold should be set as a percent, such as
- * 50 for 50% or 99 for 99%. The default is .
+ * 50 for 50% or 99 for 99%.
*
*
* This health check is automatically created and registered through CDI.
From e26e60549793ecf09b2a96d7ef315af0cb0f1750 Mon Sep 17 00:00:00 2001
From: "tim.quinn@oracle.com"
Date: Wed, 2 Dec 2020 12:56:41 -0600
Subject: [PATCH 4/4] Fix width management of new table
---
docs/se/health/01_health.adoc | 19 ++++++++++++-------
1 file changed, 12 insertions(+), 7 deletions(-)
diff --git a/docs/se/health/01_health.adoc b/docs/se/health/01_health.adoc
index e0a6e2f6a21..8284ac8c152 100644
--- a/docs/se/health/01_health.adoc
+++ b/docs/se/health/01_health.adoc
@@ -181,25 +181,30 @@ You can use Helidon-provided health checks to report various
common health check statuses:
[[built-in-health-checks-table]]
-[cols="1,1,3,20"]
+[cols="1,1,3,15,3"]
|=======
-|Built-in health check |Health check name |JavaDoc |Config properties [default value]
+|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` [`99.999`] +
+|`helidon.healthCheck.diskSpace.thresholdPercent` +
+ +
+`helidon.healthCheck.diskSpace.path`
+| `99.999` +
+
-`helidon.healthCheck.diskSpace.path` [`/`]
+`/`
|available heap memory
| `heapMemory`
| link:{javadoc-base-url-api}/HeapMemoryHealthCheck.html[`HeapMemoryHealthCheck`]
-|`helidon.healthCheck.heapMemory.thresholdPercent` [`98`]
+|`helidon.healthCheck.heapMemory.thresholdPercent`
+|`98`
|=======
The following code adds the default built-in health checks to your application:
@@ -214,8 +219,8 @@ Routing.builder()
.register(health) // <.>
.build();
----
-<.> Add built-in health checks (requires the `helidon-health-checks`
- dependency) using defaults.
+<.> 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).