Apache
Home » Documentation » Bundles

Sling Health Check Tools

Based on simple HealthCheck OSGi services, the Sling Health Check Tools ("hc" in short form) are 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, by supplying MBeans that expose the required attributes, or by implementing your own HealthCheck services.

See also:

Use cases

Health checks can be used for various purposes, for example:

The health check subsystem uses tags to select which health checks to execute so you can for example execute just the performance or security health checks once they are configured with the corresponding tags.

The out of the box health check services also allow for using them as JMX aggregators and processors, which take JMX attribute values as input and make the results accessible via JMX MBeans.

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} 
     *  This is meant to execute quickly, access to external
     *  systems, for example, should be managed asynchronously.
     */
    public Result execute();
}

Where Result is a simple immutable class that provides a Status (OK, WARN, CRITICAL etc.) and one or more log-like messages that can provide more info about what, if anything, went wrong.

public class Result implements Iterable <ResultLog.Entry> {

    public boolean isOk() {
        return getStatus().equals(Status.OK);
    }

    public Status getStatus() {
        return resultLog.getAggregateStatus();
    }

    @Override
    public Iterator<ResultLog.Entry> iterator() {
        return resultLog.iterator();
    }

    ... details omitted
}

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.

Besides executing them programmatically, Health checks can be executed via a webconsole plugin or via JMX, as described below.

SlingHealthCheck annotation

The SlingHealthCheck annotation makes it easier to specify the required HealthCheck service properties.

Here's an example from the samples module - see the annotations module for more details.

@SlingHealthCheck(
    name="Annotated Health Check Sample", 
    mbeanName="annotatedHC",
    description="Sample Health Check defined by a java annotation",
    tags={"sample","annotation"})

public class AnnotatedHealthCheckSample implements HealthCheck{

    @Override
    public Result execute() {
        ...health check code
    }
}

Health Check bundles

The Health Check subsystem consists of the following bundles:

Out-of-the-box HealthCheck services

The following default HealthCheck services are provided by the org.apache.sling.hc.core bundle:

The org.apache.sling.hc.samples bundle provides OSGi configurations that demonstrate them.

A few more Sling-specific ones are provided by the org.apache.sling.hc.support bundle:

A bridge to server-side OSGi-aware JUnit tests is provided by the JUnitHealthCheck, from the org.apache.sling.junit.healthcheck bundle.

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.

As an example, here's a ScriptableHealthCheck configuration provided by the org.apache.sling.hc.samples bundle:

Factory PID = org.apache.sling.hc.ScriptableHealthCheck
"hc.name" : "LoadedClassCount and ManagementSpecVersion are in range" 
"hc.mbean.name" : "LoadedClassCount and ManagementSpecVersion"
"hc.tags" : [jvm, script]
"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 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 module.

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 screenshot below shows an example, as of svn revision 1513462.

Health Check Webconsole Plugin

JMX access to health checks

If the org.apache.sling.hc.jmx bundle is active, a JMX MBean is created for each HealthCheck which has the service property hc.mbean.name service property set. All health check MBeans are registered in the domain org.apache.sling.healthcheck with a type of HealthCheck.

The MBean gives access to the Result and the log, as shown on the screenshot below.

See the example configurations of the org.apache.sling.hc.samples for more details.

JConsole showing Sling Health Check MBeans

Health Checks Servlet

Starting with version 1.2.4 of the org.apache.sling.hc.core bundle, a flexible Health Checks execution servlet is available. It provides similar features to the Web Console plugin described above, with output in HTML, JSON, JSONP and TXT formats.

The Health Checks Servlet is disabled by default, to enable it create an OSGi configuration like

PID = org.apache.sling.hc.core.impl.servlet.HealthCheckExecutorServlet
servletPath = /system/health

which specifies the servlet's base path. That URL then returns an HTML page, by default with the results of all active health checks and 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.

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.

It requires the org.apache.sling.junit.core bundle which provides the server-side JUnit tests infrastructure.

The idea is to implement the smoke tests of your system, for example, as health checks. You can then run them as part of integration testing, using the Sling Testing Tools
remote testing utilities, and also as plain Health Checks for monitoring or troubleshooting Sling instances.

To use this module, configure sets of tags at /system/console/configMgr/org.apache.sling.hc.junitbridge.HealthCheckTestsProvider using the standard includeThisTag,-omitThatTag syntax, and JUnit tests will be available at /system/sling/junit/HealthChecks.html to run the corresponding Health Checks.

To run the Health Check tests at build time, see the testing/samples/integration-tests sample module.

Rev. 1695532 by bdelacretaz on Wed, 12 Aug 2015 14:16:33 +0000
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.