Author: bdelacretaz
Date: Tue Aug 13 13:11:10 2013
New Revision: 1513470
URL: http://svn.apache.org/r1513470
Log:
SLING-2987 - rewrite according to redesign
Modified:
sling/site/trunk/content/documentation/bundles/jconsole-hc.jpg
sling/site/trunk/content/documentation/bundles/sling-hc-plugin.jpg
sling/site/trunk/content/documentation/bundles/sling-health-check-tool.mdtext
Modified: sling/site/trunk/content/documentation/bundles/jconsole-hc.jpg
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/jconsole-hc.jpg?rev=1513470&r1=1513469&r2=1513470&view=diff
==============================================================================
Binary files - no diff available.
Modified: sling/site/trunk/content/documentation/bundles/sling-hc-plugin.jpg
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-hc-plugin.jpg?rev=1513470&r1=1513469&r2=1513470&view=diff
==============================================================================
Binary files - no diff available.
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=1513470&r1=1513469&r2=1513470&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:11:10 2013
@@ -1,91 +1,77 @@
Title: Sling Health Check Tool
-Based on extensible rules that check various system attributes, the Sling
Health Check Tool ("hc" in short form) is used to
-check the health of live Sling systems, based on various _system attributes_
that the rules check.
+Based on simple _HealthCheck_ OSGi services, the Sling Health Check Tool ("hc"
in short form) is used to
+check the health of live Sling systems, based on inputs like JMX MBean
attribute values, OSGi framework
+information, Sling requests status, etc.
-<div class="warning">
-This module is being extensively redesigned as part of SLING-2987 - the code
that is described here
-is available at
https://svn.apache.org/repos/asf/sling/tags/healthcheck-before-SLING-2987/ and
for now
-this page is out of sync with the current trunk code.
-</div>
-
-The rules evaluation results are available in JSON format via HTTP requests,
as a Webconsole plugin
-and via JMX.
+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.
-Custom rules can be created by supplying _RuleBuilder_ OSGi services, see the
_hc-sling_ and _sling-demo_ modules for examples.
-
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).
-## Example rules
-A set of example rules is provided as [initial content in the sling-demo
module][1].
-
-To test them, you need to add the required bundles to a Sling trunk instance,
as shown below, as the health check tool
-bundles are currently (July 2013) not included in the default Sling launchpad.
-
-1. Start a standalone Sling instance from _launchpad/builder_
-1. Optionally install the _org.apache.sling.junit.core_ bundle, version 1.0.8
or later, if you want to enable JUnit-based rules.
-1. Build the _contrib/extensions/healthcheck_ modules.
-1. From that module, install the _org.apache.sling.hc.core_ ,
_org.apache.sling.hc.rules_ , _org.apache.sling.hc.sling_ and
_org.apache.sling.hc.slingdemo_ bundles.
-1. Open the health check webconsole at _/system/console/healthcheck_ and
follow the instructions. The _org.apache.sling.hc.slingdemo_ bundle provides a
set of example rules under _/apps/hc_ , you can use that for testing.
+## What's a HealthCheck ?
-You can also see the raw output of the rules execution servlet (as admin) at
_/apps/hc/demo.healthcheck.json_
-and the example rules content at _/apps/hc/demo.tidy.infinity.json_ .
+A _HealthCheck_ is just an OSGi service that returns a _Result_.
-Rules can have a multi-value _tags_ property that allows them to be executed
in groups. Entering _sling,bundles_ as tags in the webconsole
-plugin form, or using them as selectors (
_/apps/hc/demo.healthcheck.bundles.sling.json_ ) demonstrates this feature.
+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 HealthChecks 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.
+
+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.
+
+## 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
+
+As of mid-August 2013, the `org.apache.sling.hc.samples` bundle provides OSGi
configurations that demonstrate the following HealthCheck services:
+
+ * `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.
+
+## Configuring health checks
+Health check 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
+
+Properties starting with the `hc.` prefix should be provided by all
HealthCheck services.
## Webconsole plugin
-As mentioned above, a webconsole plugin at _/system/console/healthcheck_
allows for executing health check rules, optionally selected based on their
-tags and optionally showing only results from rules that have something to
report (as in "no news is good news").
+A webconsole plugin at `/system/console/healthcheck` allows for executing
health checks, optionally selected
+based on their tags.
-The screenshot below shows an example, as of svn revision 1490286.
+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.
-## JMX interfaces
+## JMX access to health checks
+A JMX MBean is created for each HealthCheck, which gives access to the
`Result` and the log, as shown
+on the screenshot below.
+
+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_.
-### Accessing and combining JMX attributes in scripted rules
-Although the basic _jmxbeans_ rules give access to single JMX attribute values
in rules, a more powerful way to access
-JMX attributes is to use scripted rules, where mini-scripts can be written to
combine and check multiple values.
-
-The rule definition shown below, for example, checks two JMX attributes. Such
scripted rules can be written in any scripting language
-that Sling supports, selected by an extension (ecma, groovy etc.) specified in
the rule qualifier.
-
- {
- "sling:resourceType" : "sling/healthcheck/rules",
- "namespace": "script",
- "ruleName": "Example javascript expression that combines two JMX
attributes",
- "qualifier": "ecma",
- "expression":
- 'jmx.attribute("java.lang:type=ClassLoading", "LoadedClassCount")
> 100
- &&
jmx.attribute("osgi.core:type=framework,version=1.5","FrameworkStartLevel") >
1',
- "tags" : ["script","javascript", "jmx" ],
- "jcr:primaryType": "nt:unstructured"
- }
-
-### JMX access to Health Check Rules results
-Creating _org.apache.sling.hc.sling.impl.RulesMBeans_ OSGi configurations
causes the results of health
-check rules to be made available via JMX MBeans in the
_org.apache.sling.healthcheck_ JMX tree.
-
-The slingdemo module provides an [example configuration][2], which is used in
the screenshot below.
-
-To create such a configuration you need to specify the root path where rule
definitions are found in the
-repository, an optional MBean name that's used to name this set of rules below
the
-_org.apache.sling.healthcheck_ JMX tree root, and an optional set of rules
tags to select which rules
-to include.
-
-Multiple _RulesMBeans_ configurations can be used to provide various views on
the health check rules.
-This can cause a rule to appear in multiple places in the JMX tree, which is
not really a problem as the rule
-data is read-only.
+The example configurations of the `org.apache.sling.hc.samples` bundle
demonstrate the various features.
-
-
-## Known issues
-See [SLING-2822](https://issues.apache.org/jira/browse/SLING-2822) for details.
-
- [1]:
http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/healthcheck/sling-demo/src/main/resources/SLING-CONTENT/apps/hc/demo
- [2]:
http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/healthcheck/sling-demo/src/main/resources/SLING-CONTENT/apps/hc/install/org.apache.sling.hc.sling.impl.RulesMBeans-1.json
