incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bdelacre...@apache.org
Subject svn commit: r1513475 - /sling/site/trunk/content/documentation/bundles/sling-health-check-tool.mdtext
Date Tue, 13 Aug 2013 13:22:13 GMT
Author: bdelacretaz
Date: Tue Aug 13 13:22:13 2013
New Revision: 1513475

URL: http://svn.apache.org/r1513475
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=1513475&r1=1513474&r2=1513475&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:22:13 2013
@@ -1,10 +1,10 @@
 Title: Sling Health Check Tool
 
-Based on simple _HealthCheck_ OSGi services, the Sling Health Check Tool ("hc" in short form)
is used to 
+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.
 
-Health checks are easily extensible either by configuring the supplied default _HealthCheck_
services, or
+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 
@@ -12,34 +12,58 @@ accounts, JUnit tests results and the ou
 
 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 ?
+## What's a `HealthCheck` ?
+
+A `HealthCheck` is just an OSGi service that returns a `Result`.
+
+    public interface HealthCheck {
+        
+        /** Execute this health check and return a {@link Result} */
+        public Result execute();
+        
+        /** Additional (static) information about
+         *  this check. {@link Constants} defines
+         *  some well-known property names.
+         */
+        public Map<String, String> getInfo();
+    }
 
-A _HealthCheck_ is just an OSGi service that returns a _Result_.
 
 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
+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. 
 
-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
+`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. 
 
+## Health Check subsystem bundles
+The Health Check subsystem consists of the following bundles:
+
+* 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.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
+## Default `HealthCheck` services and samples
+
+A useful set of default `HealthCheck`s is provided by the `org.apache.sling.hc.healthchecks`
bundle. 
 
-As of mid-August 2013, 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 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.
+ * `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.
+`HealthCheck` services are created via OSGi configurations.
 
 Here's a `ScriptableHealthCheck` example configuration provided by the `org.apache.sling.hc.samples`
bundle:
 
@@ -51,11 +75,12 @@ Here's a `ScriptableHealthCheck` example
   expression = osgi.inactiveBundlesCount() == 0 
   language.extension = ecma
   
-Properties starting with the `hc.` prefix should be provided by all HealthCheck services.
+Properties starting with the `hc.` prefix should be provided by all `HealthCheck` services.
 
 ## Webconsole plugin
-A webconsole plugin at `/system/console/healthcheck` allows for executing health checks,
optionally selected
-based on their tags.
+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 `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.
@@ -65,13 +90,14 @@ The screenshot below shows an example, a
 ![](sling-hc-plugin.jpg)
 
 ## 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.   
+If the `org.apache.sling.hc.jmx` bundle is active, a JMX MBean is created for each `HealthCheck`.
+
+The MBean 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
+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_.
 
 The example configurations of the `org.apache.sling.hc.samples` bundle demonstrate the various
features.
 
-![](jconsole-hc.jpg)
+![](jconsole-hc.jpg)
\ No newline at end of file



Mime
View raw message