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).