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, durables, 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.
Durables: Durables 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:
Durables: Durables 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 |
DurableMismatchCheck | Check if durables are coherent across all nodes of the cluster. | |
EnvironmentStateCheck | Check the environment state of the realms. | 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 |
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:
runUMTool HealthChecker [-rname=<rname> | -xml=/path/to/xml1,...]
[-check=<checktype>[,<checktype> ...] ]
[-mode=<modetype>]
[-include=<checktype>[,<checktype> ...] ]
[-exclude=<checktype>[,<checktype> ...] ]
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.
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. |
Full Example
The following example compares the XML configuration files of two realms in a cluster. The realms are named realm0 and realm1, and their configuration files are named clustered_realm0.xml and clustered_realm1.xml.
XML configuration file clustered_realm0.xml for realm0:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NirvanaRealm name="realm0" exportDate="2016-11-08Z"
comment="Realm configuration from realm0" version="BuildIdentifier"
buildInfo="BuildIdentifier">
<ClusterSet>
<ClusterEntry name="cluster1">
<ClusterMember name="realm1" rname="nsp://localhost:11010/"
canBeMaster="true"/>
<ClusterMember name="realm0" rname="nsp://localhost:11000/"
canBeMaster="true"/>
</ClusterEntry>
</ClusterSet>
<ChannelSet>
<ChannelEntry>
<ChannelAttributesEntry name="channel1" TTL="0" capacity="5" EID="0"
clusterWide="true" jmsEngine="false" mergeEngine="false"
type="PERSISTENT_TYPE"/>
<StorePropertiesEntry HonorCapacityWhenFull="false"
SyncOnEachWrite="false" SyncMaxBatchSize="0" SyncBatchTime="0"
PerformAutomaticMaintenance="false" EnableCaching="true"
CacheOnReload="true" EnableReadBuffering="true"
ReadBufferSize="10240" Priority="4" EnableMulticast="false"
StampDictionary="0"/>
<ChannelJoinSet>
<ChannelJoinEntry filter="" hopcount="50" to="channel2"
from="channel1" allowPurge="false" archival="false"/>
</ChannelJoinSet>
</ChannelEntry>
<ChannelEntry>
<ChannelAttributesEntry name="channel2" TTL="0" capacity="0" EID="0"
clusterWide="true" jmsEngine="false" mergeEngine="false"
type="RELIABLE_TYPE"/>
<StorePropertiesEntry HonorCapacityWhenFull="false"
SyncOnEachWrite="false"
SyncMaxBatchSize="0" SyncBatchTime="0"
PerformAutomaticMaintenance="false"
EnableCaching="true" CacheOnReload="true"
EnableReadBuffering="true"
ReadBufferSize="10240" Priority="4" EnableMulticast="false"
StampDictionary="0"/>
<DurableSet>
<durableEntry name="durable1" EID="-1" outstandingEvents="0"
clusterWide="true" persistent="true"
priorityEnabled="false" shared="true"/>
</DurableSet>
</ChannelEntry>
</ChannelSet>
<QueueSet>
<QueueEntry>
<ChannelAttributesEntry name="queue1" TTL="0" capacity="0" EID="0"
clusterWide="true" jmsEngine="false" mergeEngine="false"
type="RELIABLE_TYPE"/>
<StorePropertiesEntry HonorCapacityWhenFull="false"
SyncOnEachWrite="false" SyncMaxBatchSize="0" SyncBatchTime="0"
PerformAutomaticMaintenance="true" EnableCaching="true"
CacheOnReload="true" EnableReadBuffering="true"
ReadBufferSize="10240" Priority="4" EnableMulticast="false"
StampDictionary="0"/>
</QueueEntry>
</QueueSet>
</NirvanaRealm>
XML configuration file clustered_realm1.xml for realm1:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NirvanaRealm name="realm1" exportDate="2016-11-16Z"
comment="Realm configuration from realm1"
version="BuildIdentifier" buildInfo="BuildIdentifier">
<ClusterSet>
<ClusterEntry name="cluster1">
<ClusterMember name="realm1" rname="nsp://localhost:11010/"
canBeMaster="true"/>
<ClusterMember name="realm0" rname="nsp://localhost:11000/"
canBeMaster="true"/>
</ClusterEntry>
</ClusterSet>
<ChannelSet>
<ChannelEntry>
<ChannelAttributesEntry name="channel1" TTL="0" capacity="5" EID="0"
clusterWide="true" jmsEngine="false" mergeEngine="false"
type="RELIABLE_TYPE"/>
<StorePropertiesEntry HonorCapacityWhenFull="false"
SyncOnEachWrite="false" SyncMaxBatchSize="0" SyncBatchTime="0"
PerformAutomaticMaintenance="false" EnableCaching="true"
CacheOnReload="true" EnableReadBuffering="true"
ReadBufferSize="10240" Priority="4" EnableMulticast="false"
StampDictionary="0"/>
<ChannelJoinSet>
<ChannelJoinEntry filter="" hopcount="10" to="channel2"
from="channel1" allowPurge="false" archival="false"/>
</ChannelJoinSet>
</ChannelEntry>
<ChannelEntry>
<ChannelAttributesEntry name="channel2" TTL="0" capacity="0" EID="0"
clusterWide="true" jmsEngine="false" mergeEngine="false"
type="RELIABLE_TYPE"/>
<StorePropertiesEntry HonorCapacityWhenFull="false"
SyncOnEachWrite="false" SyncMaxBatchSize="0" SyncBatchTime="0"
PerformAutomaticMaintenance="false" EnableCaching="true"
CacheOnReload="true" EnableReadBuffering="true"
ReadBufferSize="10240" Priority="4" EnableMulticast="false"
StampDictionary="0"/>
</ChannelEntry>
</ChannelSet>
<DataGroupSet>
<DataGroupEntry>
<DataGroupAttributesEntry name="dg1" id="3422373812" priority="1"
multicastenabled="false"/>
</DataGroupEntry>
</DataGroupSet>
</NirvanaRealm>
From a first analysis we can say that these two realms belong to the same cluster (cluster1) and that they both contain various stores, joins and data groups. But let's see what happens when we run the HealthChecker tool specifying both XML files and running all the checks. Here is the call of the tool (using Windows syntax) and the result:
runUMTool.bat HealthChecker -xml=clustered_realm0.xml,clustered_realm1.xml
HealthChecker Tool - Version: 1.0
XML JOIN MISMATCHES CHECK
ERROR: Join from (channel1) to (channel2) HopCount mismatch [realm1] does not
equal [realm0]
XML JNDI PROPERTIES CHECK
WARN: Realm realm0: No JNDI entry for store channel1
WARN: Realm realm0: No JNDI entry for store channel2
WARN: Realm realm0: No JNDI entry for store queue1
WARN: Realm realm1: No JNDI entry for store channel1
WARN: Realm realm1: No JNDI entry for store channel2
XML DURABLE STATUS CHECK
ERROR: Could not find durable (durable1) on realm [realm1] but it is present
on [realm0]
XML CLUSTERED STORE MISMATCHES CHECK
WARN: Store (channel1) Type mismatch [realm1] does not equal [realm0]
ERROR: Could not find store (queue1) on realm [realm1] but it is present
on realm [realm0]
XML DATAGROUP MISMATCHES CHECK
ERROR: Could not find Data Group (dg1) on realm [realm0] but it is present
on realm [realm1]
XML CLUSTERED STORE WARNINGS CHECK
These errors and warnings tell us:
Joins: a join between two clusterwide channels has to be the same on all the nodes - in our case there is a mismatch in the HopCount;
JNDIs: these simple warnings are saying: "Are you sure that you don't need any JNDI for these stores?";
Durables: if a durable is clusterwide, then it has to be present on all the other nodes (and it has to be the same);
Stores: if a store is clusterwide, then it has to be the same on all the other nodes.
Datagroups: the same rule applies for datagroups, which are always clusterwide and have to be present on all the other nodes.
