Author: bdelacretaz
Date: Tue Aug 13 13:31:42 2013
New Revision: 1513478
URL: http://svn.apache.org/r1513478
Log:
SLING-2987 - health check docs tweaks
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=1513478&r1=1513477&r2=1513478&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 Aug 13 13:31:42 2013
@@ -7,9 +7,6 @@ information, Sling requests status, etc.
Health checks are easily extensible either by configuring the supplied default
`HealthCheck` services, or
by implementing your own services.
-Default rules are provided to check JMX MBeans, OSGi bundle states, disabling
of default Sling
-accounts, JUnit tests results and the output of scripts written in any
language supported by Sling.
-
The source code of the hc modules is at
[http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/healthcheck](http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/healthcheck).
## What's a `HealthCheck` ?
@@ -31,55 +28,56 @@ A `HealthCheck` is just an OSGi service
The Result provides a _Status_ (OK, WARN, CRITICAL etc.) and a human-readable
log which provides additional info, including optional DEBUG messages
that help troubleshooting. The Result log is not stricly tied to a logging
model, so `HealthCheck`s are free to invent their own types of logging messages
-if needed. See the `org.apache.sling.hc.api.Result` class in the for more
details.
+if needed. See the `org.apache.sling.hc.api.Result` class for more details.
+
+`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.
-`HealthCheck` services can be selected for execution based on their _tags_.
The `HealthCheckFilter` utility
-accepts positive and negative tag parameters, so that `-security,sling` for
example selects all `HealthCheck`
-having the _sling_ tag but not the _security_ tag.
+Besides executing them programatically, Health checks can be executed via a
webconsole plugin or via JMX,
+as described below.
-## Health Check subsystem bundles
-The Health Check subsystem consists of the following bundles:
+## Health Check bundles
+The Health Check subsystem consists of the following bundles, which are
described below in more detail:
* The only required bundle is `org.apache.sling.hc.api` which provides the API
and some utility classes.
-* `org.apache.sling.hc.healthchecks` provides default `HealthCheck` services,
described below.
-* `org.apache.sling.hc.webconsole` provides the Webconsole plugin described
below.
+* `org.apache.sling.hc.healthchecks` provides default `HealthCheck` services.
+* `org.apache.sling.hc.webconsole` provides the Webconsole plugin.
* `org.apache.sling.hc.jmx` provides JMX MBeans to execute `HealthCheck`s.
* `org.apache.sling.hc.samples` provides sample OSGi configurations that
demonstrate the default `HealthCheck`s. These configurations are provided as
Sling content, so the Sling Installer is required to activate them.
-## Executing health checks
-Besides executing them programatically, Health checks can be executed via a
webconsole plugin or via JMX,
-see below for more details.
-
-## Default `HealthCheck` services and samples
+## Out-of-the-box `HealthCheck` services
A useful set of default `HealthCheck`s is provided by the
`org.apache.sling.hc.healthchecks` bundle.
-The `org.apache.sling.hc.samples` bundle provides OSGi configurations that
demonstrate the following `HealthCheck` services:
+The `org.apache.sling.hc.samples` bundle provides OSGi configurations that
demonstrate them.
* `JmxAttributeHealthCheck` checks the value of a single JMX attribute and
supports ranges like _between 12 and 42_.
* `SlingRequestStatusHealthCheck` checks the HTTP status of Sling requests.
* `ScriptableHealthCheck` evaluates an expression written in any scripting
language that Sling supports, and provides bindings to access JMX attributes
and OSGi bundles states.
* `DefaultLoginsHealthCheck` can be used to verify that the default Sling
logins fail.
- * `CompositeHealthCheck` executes a set of `HealthCheck` selected by tags,
useful to get higher-level management views.
+ * `CompositeHealthCheck` executes a set of `HealthCheck` selected by tags,
useful for creating higher-level checks.
## Configuring health checks
`HealthCheck` services are created via OSGi configurations.
Here's a `ScriptableHealthCheck` example configuration provided by the
`org.apache.sling.hc.samples` bundle:
- PID = org.apache.sling.hc.ScriptableHealthCheck.1523a6db-12324
- Factory PID = org.apache.sling.hc.ScriptableHealthCheck
- hc.mbean.name = InactiveBundlesCheck
- hc.name = No inactive bundles
- hc.tags = [bundles, script]
- expression = osgi.inactiveBundlesCount() == 0
- language.extension = ecma
+ Factory PID = org.apache.sling.hc.ScriptableHealthCheck
+ PID = org.apache.sling.hc.ScriptableHealthCheck.1523a6db-12324
+ hc.mbean.name = InactiveBundlesCheck
+ hc.name = No inactive bundles
+ hc.tags = [bundles, script]
+ expression = osgi.inactiveBundlesCount() == 0
+ language.extension = ecma
-Properties starting with the `hc.` prefix should be provided by all
`HealthCheck` services.
+The service properties starting with the `hc.` prefix in this example should
be provided by all
+`HealthCheck` services.
## 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
+at `/system/console/healthcheck` allows for executing health checks,
optionally selected
based on their tags (positive and negative selection, see `HealthCheckFilter`
mention above).
The DEBUG logs of health checks can optionally be displayed, and an option
allows for showing only health
@@ -96,8 +94,9 @@ The MBean gives access to the `Result` a
The MBean name defaults to the `hc.name` service property of the
_`HealthCheck`_, but if an
`hc.mbean.name` property is provided it is used instead. That property can
include a a slash
-(as in `composite/security`) to define the MBean service name, which by
default is _HealthCheck_.
+(like `CompositeHealthCheck/script` in the screenshot) to define the MBean
service name,
+which by default is _HealthCheck_.
-The example configurations of the `org.apache.sling.hc.samples` bundle
demonstrate the various features.
+See the example configurations of the `org.apache.sling.hc.samples` for more
details.
\ No newline at end of file
