Author: ghenzler
Date: Tue Oct 18 11:36:54 2016
New Revision: 1765416
URL: http://svn.apache.org/viewvc?rev=1765416&view=rev
Log:
SLING-6126 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=1765416&r1=1765415&r2=1765416&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 Oct 18 11:36:54 2016
@@ -80,8 +80,8 @@ Here's an example from the `samples` mod
mbeanName="annotatedHC",
description="Sample Health Check defined by a java annotation",
tags={"sample","annotation"})
-
- public class AnnotatedHealthCheckSample implements HealthCheck{
+
+ public class AnnotatedHealthCheckSample implements HealthCheck {
@Override
public Result execute() {
@@ -95,7 +95,6 @@ The Health Check subsystem consists of t
* The only required bundle is `org.apache.sling.hc.core` which provides the
API, some utility classes and some generally useful `HealthCheck` services.
* `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.hc.jmx` provides JMX MBeans that execute `HealthCheck`s.
* `org.apache.sling.junit.healthcheck` provides a `HealthCheck` service that
executes JUnit tests in the server-side OSGi context.
* `org.apache.sling.hc.samples` provides sample OSGi configurations and
`HealthCheck` services. The sample configurations are provided as Sling
content, so the Sling Installer is required to activate them.
* `org.apache.sling.hc.junit.bridge` makes selected Health Checks available as
server-side JUnit tests. See below for more info.
@@ -121,9 +120,20 @@ the `org.apache.sling.junit.healthcheck
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.
-## Configuring health checks
-`HealthCheck` services are created via OSGi configurations, the details of
which are defined by each
-service implementation.
+## Configuring Health Checks
+`HealthCheck` services are created via OSGi configurations. Generic health
check service properties are interpreted by the health check executor service.
Custom health check service properties can be used by the health check
implementation itself to configure its behaviour.
+
+The following generic Health Check properties may be used for all checks:
+
+Property | Type | Description
+----------- | -------- | ------------
+hc.name | String | The name of the health check as shown in UI
+hc.tags | String[] | List of tags: Both Felix Console Plugin and Health
Check servlet support selecting relevant checks by providing a list of tags
+hc.mbean.name | String | Makes the HC result available via given MBean name.
If not provided no MBean is created for that `HealthCheck`
+hc.async.cronExpression | String | Used to schedule the execution of a
`HealthCheck` at regular intervals, using a cron expression as specified by the
[Sling Scheduler]({{ refs.scheduler-service-commons-scheduler.path }}) module.
+hc.resultCacheTtlInMs | Long | Overrides the global default TTL as configured
in health check executor for health check responses (since v1.2.6 of core)
+
+All service properties are optional.
As an example, here's a `ScriptableHealthCheck` configuration provided by the
`org.apache.sling.hc.samples` bundle:
@@ -134,19 +144,23 @@ As an example, here's a `ScriptableHealt
"expression" : "jmx.attribute('java.lang:type=ClassLoading',
'LoadedClassCount') > 10 && jmx.attribute('java.lang:type=Runtime',
'ManagementSpecVersion') > 1"
"language.extension" : "ecma"
-The service properties starting with the `hc.` prefix in this example should
be provided by all `HealthCheck` services. The `hc.mbean.name`
-is optional, if not provided no MBean is created for that `HealthCheck`.
+The service properties starting with the `hc.` prefix in this example should
be provided by all `HealthCheck` services.
+
+## Configuring the Health Check Executor
+The health check executor can **optionally** be configured via service PID
`org.apache.sling.hc.core.impl.executor.HealthCheckExecutorImpl`:
-The optional `hc.async.cronExpression` service property is used to schedule
the execution of a `HealthCheck` at regular intervals,
-using a cron expression as specified by the [Sling Scheduler]({{
refs.scheduler-service-commons-scheduler.path }}) module.
+Property | Type | Default | Description
+----------- | -------- | ------ | ------------
+timeoutInMs | Long | 2000ms | Timeout in ms until a check is marked as
timed out
+longRunningFutureThresholdForCriticalMs | Long | 300000ms = 5min | Threshold
in ms until a check is marked as 'exceedingly' timed out and will marked
CRITICAL instead of WARN only
+resultCacheTtlInMs | Long | 2000ms | Result Cache time to live - results will
be cached for the given time
## Webconsole plugin
If the `org.apache.sling.hc.webconsole` bundle is active, a webconsole plugin
at `/system/console/healthcheck` allows for executing health checks,
optionally selected
based on their tags (positive and negative selection, see the
`HealthCheckFilter` mention above).
-The DEBUG logs of health checks can optionally be displayed, and an option
allows for showing only health
-checks that have a non-OK status.
+The DEBUG logs of health checks can optionally be displayed, and an option
allows for showing only health checks that have a non-OK status.
The screenshot below shows an example, as of svn revision 1513462.
@@ -176,7 +190,7 @@ which specifies the servlet's base path.
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 *the Health Checks Servlet doesn't do any access control by itself*,
so make sure the configured path is secure before enabling it.
+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.
## 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.
