incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r874462 - in /websites/staging/sling/trunk/content: ./ documentation/bundles/jconsole-hc.jpg documentation/bundles/sling-hc-plugin.jpg documentation/bundles/sling-health-check-tool.html
Date Tue, 13 Aug 2013 13:11:20 GMT
Author: buildbot
Date: Tue Aug 13 13:11:19 2013
New Revision: 874462

Log:
Staging update by buildbot for sling

Modified:
    websites/staging/sling/trunk/content/   (props changed)
    websites/staging/sling/trunk/content/documentation/bundles/jconsole-hc.jpg
    websites/staging/sling/trunk/content/documentation/bundles/sling-hc-plugin.jpg
    websites/staging/sling/trunk/content/documentation/bundles/sling-health-check-tool.html

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Aug 13 13:11:19 2013
@@ -1 +1 @@
-1513104
+1513470

Modified: websites/staging/sling/trunk/content/documentation/bundles/jconsole-hc.jpg
==============================================================================
Binary files - no diff available.

Modified: websites/staging/sling/trunk/content/documentation/bundles/sling-hc-plugin.jpg
==============================================================================
Binary files - no diff available.

Modified: websites/staging/sling/trunk/content/documentation/bundles/sling-health-check-tool.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/sling-health-check-tool.html
(original)
+++ websites/staging/sling/trunk/content/documentation/bundles/sling-health-check-tool.html
Tue Aug 13 13:11:19 2013
@@ -85,76 +85,62 @@
       
       
       <h1>Sling Health Check Tool</h1>
-      <p>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 <em>system attributes</em>
that the rules check.</p>
-<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>
-
-<p>The rules evaluation results are available in JSON format via HTTP requests, as
a Webconsole plugin 
-and via JMX.</p>
+      <p>Based on simple <em>HealthCheck</em> 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.</p>
+<p>Health checks are easily extensible either by configuring the supplied default <em>HealthCheck</em>
services, or
+by implementing your own services.  </p>
 <p>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.</p>
-<p>Custom rules can be created by supplying <em>RuleBuilder</em> OSGi services,
see the <em>hc-sling</em> and <em>sling-demo</em> modules for examples.</p>
 <p>The source code of the hc modules is at <a href="http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/healthcheck">http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/healthcheck</a>.</p>
-<h2 id="example-rules">Example rules</h2>
-<p>A set of example rules is provided as <a href="http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/healthcheck/sling-demo/src/main/resources/SLING-CONTENT/apps/hc/demo">initial
content in the sling-demo module</a>.</p>
-<p>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.</p>
-<ol>
-<li>Start a standalone Sling instance from <em>launchpad/builder</em></li>
-<li>Optionally install the <em>org.apache.sling.junit.core</em> bundle,
version 1.0.8 or later, if you want to enable JUnit-based rules.</li>
-<li>Build the <em>contrib/extensions/healthcheck</em> modules.</li>
-<li>From that module, install the <em>org.apache.sling.hc.core</em> , 
<em>org.apache.sling.hc.rules</em> , <em>org.apache.sling.hc.sling</em>
and <em>org.apache.sling.hc.slingdemo</em> bundles.</li>
-<li>Open the health check webconsole at <em>/system/console/healthcheck</em>
and follow the instructions. The <em>org.apache.sling.hc.slingdemo</em> bundle
provides a set of example rules under <em>/apps/hc</em> , you can use that for
testing.</li>
-</ol>
-<p>You can also see the raw output of the rules execution servlet (as admin) at <em>/apps/hc/demo.healthcheck.json</em>

-and the example rules content at <em>/apps/hc/demo.tidy.infinity.json</em> .</p>
-<p>Rules can have a multi-value <em>tags</em> property that allows them
to be executed in groups. Entering <em>sling,bundles</em> as tags in the webconsole

-plugin form, or using them as selectors ( <em>/apps/hc/demo.healthcheck.bundles.sling.json</em>
) demonstrates this feature.</p>
+<h2 id="whats-a-healthcheck">What's a HealthCheck ?</h2>
+<p>A <em>HealthCheck</em> is just an OSGi service that returns a <em>Result</em>.</p>
+<p>The Result provides a <em>Status</em> (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 <code>org.apache.sling.hc.api.Result</code> class in the for
more details. </p>
+<p>HealthCheck services can be selected for execution based on their <em>tags</em>.
The <em>HealthCheckFilter</em> utility 
+accepts positive and negative tag parameters, so that <code>-security,sling</code>
for example selects all HealthCheck
+having the <em>sling</em> tag but not the <em>security</em> tag.
</p>
+<h2 id="executing-health-checks">Executing health checks</h2>
+<p>Besides executing them programatically, Health checks can be executed via a webconsole
plugin or via JMX, 
+see below for more details.</p>
+<h2 id="default-healthcheck-services-and-samples">Default HealthCheck services and
samples</h2>
+<p>As of mid-August 2013, the <code>org.apache.sling.hc.samples</code>
bundle provides OSGi configurations that demonstrate the following HealthCheck services:</p>
+<ul>
+<li><code>JmxAttributeHealthCheck</code> checks the value of a single JMX
attribute and supports ranges like <em>between 12 and 42</em>.  </li>
+<li><code>SlingRequestStatusHealthCheck</code> checks the HTTP status of
Sling requests.  </li>
+<li><code>ScriptableHealthCheck</code> evaluates an expression written
in any scripting language that Sling supports, and provides bindings to access JMX attributes
and OSGi bundles states. </li>
+<li><code>DefaultLoginsHealthCheck</code> can be used to verify that the
default Sling logins fail.  </li>
+<li><code>CompositeHealthCheck</code> executes a set of HealthCheck selected
by tags, useful to get higher-level management views.</li>
+</ul>
+<h2 id="configuring-health-checks">Configuring health checks</h2>
+<p>Health check services are created via OSGi configurations.</p>
+<p>Here's a <code>ScriptableHealthCheck</code> example configuration provided
by the <code>org.apache.sling.hc.samples</code> bundle:</p>
+<p>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</p>
+<p>Properties starting with the <code>hc.</code> prefix should be provided
by all HealthCheck services.</p>
 <h2 id="webconsole-plugin">Webconsole plugin</h2>
-<p>As mentioned above, a webconsole plugin at <em>/system/console/healthcheck</em>
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").</p>
-<p>The screenshot below shows an example, as of svn revision 1490286.</p>
+<p>A webconsole plugin at <code>/system/console/healthcheck</code> allows
for executing health checks, optionally selected
+based on their tags.</p>
+<p>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.</p>
+<p>The screenshot below shows an example, as of svn revision 1513462.</p>
 <p><img alt="" src="sling-hc-plugin.jpg" /></p>
-<h2 id="jmx-interfaces">JMX interfaces</h2>
-<h3 id="accessing-and-combining-jmx-attributes-in-scripted-rules">Accessing and combining
JMX attributes in scripted rules</h3>
-<p>Although the basic <em>jmxbeans</em> 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.</p>
-<p>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.
</p>
-<div class="codehilite"><pre><span class="p">{</span>
-    &quot;<span class="n">sling</span><span class="p">:</span><span
class="n">resourceType</span>&quot; <span class="p">:</span> &quot;<span
class="n">sling</span><span class="o">/</span><span class="n">healthcheck</span><span
class="o">/</span><span class="n">rules</span>&quot;<span class="p">,</span>
-    &quot;<span class="n">namespace</span>&quot;<span class="p">:</span>
&quot;<span class="n">script</span>&quot;<span class="p">,</span>
-    &quot;<span class="n">ruleName</span>&quot;<span class="p">:</span>
&quot;<span class="n">Example</span> <span class="n">javascript</span>
<span class="n">expression</span> <span class="n">that</span> <span
class="n">combines</span> <span class="n">two</span> <span class="n">JMX</span>
<span class="n">attributes</span>&quot;<span class="p">,</span>
-    &quot;<span class="n">qualifier</span>&quot;<span class="p">:</span>
&quot;<span class="n">ecma</span>&quot;<span class="p">,</span>
-    &quot;<span class="n">expression</span>&quot;<span class="p">:</span>

-        <span class="s">&#39;jmx.attribute(&quot;java.lang:type=ClassLoading&quot;,
&quot;LoadedClassCount&quot;) &gt; 100 </span>
-<span class="s">        &amp;&amp; jmx.attribute(&quot;osgi.core:type=framework,version=1.5&quot;,&quot;FrameworkStartLevel&quot;)
&gt; 1&#39;</span><span class="p">,</span>
-    &quot;<span class="n">tags</span>&quot; <span class="p">:</span>
<span class="p">[</span>&quot;<span class="n">script</span>&quot;<span
class="p">,</span>&quot;<span class="n">javascript</span>&quot;<span
class="p">,</span> &quot;<span class="n">jmx</span>&quot; <span
class="p">],</span>
-    &quot;<span class="n">jcr</span><span class="p">:</span><span
class="n">primaryType</span>&quot;<span class="p">:</span> &quot;<span
class="n">nt</span><span class="p">:</span><span class="n">unstructured</span>&quot;
-<span class="p">}</span>
-</pre></div>
-
-
-<h3 id="jmx-access-to-health-check-rules-results">JMX access to Health Check Rules
results</h3>
-<p>Creating  <em>org.apache.sling.hc.sling.impl.RulesMBeans</em> OSGi configurations
causes the results of health 
-check rules to be made available via JMX MBeans in the <em>org.apache.sling.healthcheck</em>
JMX tree.</p>
-<p>The slingdemo module provides an <a href="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">example
configuration</a>, which is used in the screenshot below.</p>
-<p>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 
-<em>org.apache.sling.healthcheck</em> JMX tree root,  and an optional set of
rules tags to select which rules 
-to include.</p>
-<p>Multiple <em>RulesMBeans</em> 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.</p>
+<h2 id="jmx-access-to-health-checks">JMX access to health checks</h2>
+<p>A JMX MBean is created for each HealthCheck, which gives access to the <code>Result</code>
and the log, as shown
+on the screenshot below.   </p>
+<p>The MBean name defaults to the <code>hc.name</code> service property
of the <em>HealthCheck</em>, but if an
+<code>hc.mbean.name</code> property is provided it is used instead. That property
can include a a slash 
+(as in <code>composite/security</code>) to define the MBean service name, which
by default is <em>HealthCheck</em>.</p>
+<p>The example configurations of the <code>org.apache.sling.hc.samples</code>
bundle demonstrate the various features.</p>
 <p><img alt="" src="jconsole-hc.jpg" /></p>
-<h2 id="known-issues">Known issues</h2>
-<p>See <a href="https://issues.apache.org/jira/browse/SLING-2822">SLING-2822</a>
for details.</p>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1512255 by bdelacretaz on Fri, 9 Aug 2013 11:14:51 +0000
+        Rev. 1513470 by bdelacretaz on Tue, 13 Aug 2013 13:11:10 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project



Mime
View raw message