You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by gh...@apache.org on 2017/05/09 05:51:04 UTC
svn commit: r1794498 -
/sling/site/trunk/content/documentation/bundles/sling-health-check-tool.mdtext
Author: ghenzler
Date: Tue May 9 05:51:04 2017
New Revision: 1794498
URL: http://svn.apache.org/viewvc?rev=1794498&view=rev
Log:
SLING-6698 SLING-6773 Updated documentation
Modified:
sling/site/trunk/content/documentation/bundles/sling-health-check-tool.mdtext
Modified: sling/site/trunk/content/documentation/bundles/sling-health-check-tool.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-health-check-tool.mdtext?rev=1794498&r1=1794497&r2=1794498&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-health-check-tool.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/sling-health-check-tool.mdtext Tue May 9 05:51:04 2017
@@ -10,13 +10,17 @@ supplying MBeans that expose the require
See also:
* Source code at [http://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/healthcheck](http://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/healthcheck)
-* adaptTo 2013 slides about Health Checks at [http://www.slideshare.net/bdelacretaz/slinghc-bdelacretazadaptto2013](http://www.slideshare.net/bdelacretaz/slinghc-bdelacretazadaptto2013)
+* adaptTo slides about Health Checks: [Introduction](http://www.slideshare.net/bdelacretaz/slinghc-bdelacretazadaptto2013) and [Health Check Executor](https://adapt.to/content/dam/adaptto/production/presentations/2014/adaptTo2014-Sling-Health-Checks-New-And-Noteworthy-Georg-Henzler.pdf/_jcr_content/renditions/original.media_file.download_attachment.file/adaptTo2014-Sling-Health-Checks-New-And-Noteworthy-Georg-Henzler.pdf)
## Use cases
-Health checks can be used for various purposes, for example:
+Generally health checks have two high level use cases:
+* Operations teams checking sling instances for their internal state manually
+* Load balancers can query the health of a sling instance and decide to take it out or back into the list of used backends automatically
-* Verify that performance counters are in range.
-* Run smoke tests at system startup and emit warnings or disable the instance if they fail.
+The strength of Health Checks are to surface internal Sling state for external use:
+
+* Verify that performance counters are in range
+* Run smoke tests at system startup
* Check that all OSGi bundles are up and running
* Check that demo content has been removed from a production system
* Check that demo accounts are disabled
@@ -62,13 +66,14 @@ can provide more info about what, if any
... details omitted
}
-`HealthCheck` services can be selected for execution based on their `hc.tags` multi-value service property.
+## Executing Health Checks
+
+Health Checks can be executed via a [webconsole plugin](#webconsoleplugin), the [health check servlet](#healthcheckservlet) or via [JMX](#jmxaccesstohealthchecks). `HealthCheck` services can be selected for execution based on their `hc.tags` multi-value service property.
The `HealthCheckFilter` utility accepts positive and negative tag parameters, so that `-security,sling`
selects all `HealthCheck` having the `sling` tag but not the `security` tag, for example.
-Besides executing them programmatically, Health checks can be executed via a webconsole plugin or via JMX,
-as described below.
+For advanced use cases it is also possible to use the API directly by using the interface `org.apache.sling.hc.api.execution.HealthCheckExecutor`.
### SlingHealthCheck annotation
The `SlingHealthCheck` annotation makes it easier to specify the required `HealthCheck` service properties.
@@ -92,7 +97,7 @@ Here's an example from the `samples` mod
## Health Check bundles
The Health Check subsystem consists of the following bundles:
-* The only required bundle is `org.apache.sling.hc.core` which provides the API, some utility classes and some generally useful `HealthCheck` services.
+* The only required bundles are `org.apache.sling.hc.api` which provides the API and `org.apache.sling.hc.core` which provides some utility classes and some generally useful `HealthCheck` services (e.g. the health check executor)
* `org.apache.sling.hc.support` provides more Sling-specific `HealthCheck` services.
* `org.apache.sling.hc.webconsole` provides the Webconsole plugin described below.
* `org.apache.sling.junit.healthcheck` provides a `HealthCheck` service that executes JUnit tests in the server-side OSGi context.
@@ -113,9 +118,10 @@ A few more Sling-specific ones are provi
* `SlingRequestStatusHealthCheck` checks the HTTP status of Sling requests.
* `DefaultLoginsHealthCheck` can be used to verify that the default Sling logins fail.
-
+ * `ThreadUsageHealthCheck` can be used to monitor for deadlocks using JRE ThreadMXBean (see [SLING-6698](https://issues.apache.org/jira/browse/SLING-6698) )
+
A bridge to server-side OSGi-aware JUnit tests is provided by the `JUnitHealthCheck`, from
-the `org.apache.sling.junit.healthcheck ` bundle.
+the `org.apache.sling.junit.healthcheck` bundle.
The `org.apache.sling.hc.samples` bundle provides an example `OsgiScriptBindingsProvider` for the default `ScriptableHealthCheck`,
which provides OSGi-related information to health check script expressions.
@@ -177,9 +183,9 @@ See the example configurations of the `o
-## Health Checks Servlet
+## Health Check Servlet
Starting with version 1.2.4 of the `org.apache.sling.hc.core` bundle, a flexible Health Checks execution servlet is available. It provides
-similar features to the Web Console plugin described above, with output in HTML, JSON, JSONP and TXT formats.
+similar features to the Web Console plugin described above, with output in HTML, JSON (plain or jsonp) and TXT (concise or verbose) formats (see HTML format rendering page for more documentation).
The Health Checks Servlet is disabled by default, to enable it create an OSGi configuration like
@@ -187,10 +193,9 @@ The Health Checks Servlet is disabled by
servletPath = /system/health
which specifies the servlet's base path. That URL then returns an HTML page, by default with the results of all active health checks and
-with instructions at the end of the page about URL parameters which can be used to select specific Health Checks and control their execution
-and output format.
+with instructions at the end of the page about URL parameters which can be used to select specific Health Checks and control their execution and output format.
-Note that by design **the Health Checks Servlet doesn't do any access control by itself** to ensure it can detect unhealthy states of the authentication itself. Make sure the configured path is only accessible to relevant infranstructure and operations people. Usually all `/system/*` paths are only accessible from a local network and not routed to the Internet.
+Note that by design **the Health Checks Servlet doesn't do any access control by itself** to ensure it can detect unhealthy states of the authentication itself. Make sure the configured path is only accessible to relevant infrastructure and operations people. Usually all `/system/*` paths are only accessible from a local network and not routed to the Internet.
## Health Checks as server-side JUnit tests
The `org.apache.sling.hc.junit.bridge` bundle makes selected Health Checks available as server-side JUnit tests.