Running a Configuration Health Check
Overview
The HealthChecker is a tool for checking the correctness of a realm or cluster configuration.
The tool is primarily intended for use by Software AG support staff for analyzing possible problems in customer configurations, but you might also find it useful for checking your configuration.
The tool can be used in the following ways:
To check the configuration of a live realm (which can be a single entity or a node of a cluster) or a cluster. If the realm is a node of the cluster, the checks will also be automatically executed against all the other cluster members.
To do an offline check of the configuration of a realm or cluster, based on configuration information that has been exported to XML files. Each such XML file contains the configuration data of a realm, regarding channels, queues, named objects, datagroups, etc. The tool will only run the checks against all the cluster members if their XML paths are given explicitly in the call of the tool.
Typical configuration aspects that can be checked in a clustered realm are:
Datagroups: Datagroups belonging to a cluster must be present on all nodes of the cluster and their attributes must be the same.
Named Objects: Named objects belonging to clusterwide channels should also be clusterwide. They must be present on all nodes of the cluster and their attributes must be the same.
Joins: Joins between clusterwide channels must be present on all nodes of the cluster and their attributes have to be the same.
Stores: Stores belonging to a cluster must be present on all nodes of the cluster and their attributes and properties must be the same.
Typical configuration aspects that can be checked in a non-clustered realm are:
Named Objects: Named objects belonging to a non-clustered realm must be non-clusterwide and must be attached to a non-clusterwide channel.
Stores: Some store configurations may impact the performance of the system and they need to be highlighted.
Checks against a live realm
The checks that can be run against a live realm are the following:
Name of Check | Description | Default check? |
DataGroupMismatchCheck | Check if datagroups are coherent across all nodes of the cluster. | Y |
NamedObjectMismatchCheck | Check if named objects are coherent across all nodes of the cluster. | Y |
NamedObjectLargeStoreCheck | Check the number of remaining events to be consumed in a shared named object. If the number is greater than the threshold a warning will be displayed. The default value for the threshold is 1000. This check takes an additional parameter -threshold that allows you to specify a custom value for the threshold. | Y |
EnvironmentStateCheck | Check and display the status of a running environment. | Y |
FixLevelCheck | Check if the nodes of a given cluster have matching fix levels. | Y |
JNDIStatusCheck | Check JNDI status and mismatches for stores. | Y |
JoinMismatchCheck | Check if joins are coherent across all nodes of the cluster. | Y |
ResourcesSafetyLimitsCheck | Check that channel/queue resources have either TTL or Capacity configured to a non-zero value. If both of these values are zero, this means that the channel/queue is not configured with any safety limits. | |
StoreMemoryCheck | Checks the memory usage of stores. | Y |
StoreMismatchCheck | Check if stores are coherent across all nodes of the cluster. | Y |
StoreWarningsCheck | Check store warnings on the specified realm. | |
A "Y" in the column "Default check?" indicates that the check is included in the -mode=default setting (see the topic The -mode parameter below).
Checks against a realm's stored XML configuration
The checks that can be run against a stored XML configuration are the following:
Name of Check | Description | Default check? |
XMLDataGroupMismatchCheck | Check if datagroups are coherent across all nodes of the cluster. | Y |
XMLNamedObjectMismatchCheck | Check if named objects are coherent across all nodes of the cluster. | Y |
XMLFixLevelCheck | Check if the nodes of a given cluster have matching fix levels. | Y |
XMLJNDIStatusCheck | Check JNDI status and mismatches for stores. | Y |
XMLJoinMismatchCheck | Check if joins are coherent across all nodes of the cluster. | Y |
XMLResourcesSafetyLimitsCheck | Check that channel/queue resources have either TTL or Capacity configured to a non-zero value. If both of these values are zero, this means that the channel/queue is not configured with any safety limits. | |
XMLStoreMismatchCheck | Check if stores are coherent across all nodes of the cluster. | Y |
XMLStoreWarningsCheck | Check store warnings on the specified realm. | |
Command Usage
The syntax is as follows:
Displaying help text
To display a help text showing a summary of the command usage, call the HealthChecker without parameters:
runUMTool HealthChecker
Running a health check of a running realm
runUMTool HealthChecker -rname=–rname=nsp://localhost:11000
This will run the HealthChecker tool against the given running realm.
Running a health check of a stored realm configuration
runUMTool HealthChecker -xml=/path/to/xml1.xml, /path/to/xml2.xml
This will run the HealthChecker tool against the realm configurations stored in the given XML files.
The -check parameter
This parameter allows you to explicitly specify the check or checks that you want to be executed. No other checks will be included. This parameter can only be used together with the -rname or -xml parameter; the other additional parameters have no meaning in the context of -check so they can't be used.
Example - Execute only the Store Warnings Check check against the running realm:
runUMTool HealthChecker –rname=nsp://localhost:11000
-check=StoreWarningsCheck
Example - Execute only the Store Warnings Check and Fix Level Check checks against the running realm:
runUMTool HealthChecker –rname=nsp://localhost:11000
-check=StoreWarningsCheck, FixLevelCheck
The -mode parameter
This parameter allows you to select a predefined set of checks without having to name the checks explicitly. The -mode and -check parameters are mutually exclusive.
The mode parameter can take one of the following values:
default - this value selects the recommended minimal subset of checks. This is the default option.
all - this mode selects all checks.
If neither -mode nor -check is specified, the default set of checks will be executed.
The -include and -exclude parameters
You can use the -include and -exclude parameters to further refine the set of checks that have been selected by the -mode parameter. You can use -include and -exclude in the same call of the health checker, as long as they do not specify the same check.
include - Run all checks from the set defined by the
-mode parameter, and additionally include the check or checks specified by this parameter. The parameter may contain a single check or a comma-separated list of checks.
exclude - Run all checks from the set defined by the
-mode parameter, except the specified check or checks. The parameter may contain a single check or a comma-separated list of checks.
The -<additionalParameter> parameters
Some of the health checks allow you to specify one or more additional parameters when calling the HealthChecker. The name and purpose of each additional parameter is specific to the individual health check being run.
For example, the NamedObjectLargeStoreCheck check allows you to specify the additional parameter -threshold=<value>, which defines a threshold for the number of remaining events to be consumed in a shared named object.
The following general rules apply:
Each additional parameter has a default value, so if you do not specify the additional parameters explicitly, the default values will be taken.
If multiple additional parameters and multiple checks are specified, each individual check uses only its own additional parameters.
The additional parameters can be given in any order.
Checks that do not require additional parameters will ignore the additional parameters.
Syntax Examples
Example - Execute all available checks for live realm check:
runUMTool HealthChecker –rname=nsp://localhost:11000 -mode=all
Example - Execute all the available checks except the ones mentioned.
runUMTool HealthChecker –rname=nsp://localhost:11000
-mode=all –exclude=JNDIStatusCheck, FixLevelCheck, JoinMismatchCheck
Example - Execute the default set of checks, adding the StoreWarningsCheck which is not part of the default set.
runUMTool HealthChecker –rname=nsp://localhost:11000
-mode=default –include= StoreWarningsCheck
Example - Execute the default set of checks but excluding the JNDIStatusCheck, FixLevelCheck and adding the StoreWarningsCheck.
runUMTool HealthChecker –rname=nsp://localhost:11000
-mode=default –include= StoreWarningsCheck
–exclude=JNDIStatusCheck, FixLevelCheck
Note: The previous examples are based on live checks using the -realm parameter. The same logic applies if you use the -xml parameter instead, but the names of the checks need to be adapted to the appropriate XML checks.