Running a Configuration Health Check
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.
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 checks that can be run against a live realm or against its XML representation are the following:
Name of Check | Description |
JNDIStatusCheck | Check JNDI status and mismatches for stores |
StoreMismatchCheck | Check if stores are coherent across all nodes of the cluster |
JoinMismatchCheck | Check if joins are coherent across all nodes of the cluster |
EnvironmentStateCheck | Check the environment state of the realms (only live) |
StoreClusterWarningsCheck | Check store warnings on all nodes of the cluster |
DataGroupMismatchCheck | Check if datagroups are coherent across all nodes of the cluster |
StoreWarningsCheck | Check store warnings on the specified realm |
DurableMismatchCheck | Check if durables are coherent across all nodes of the cluster |
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.
Live analysis
In order to run the HealthChecker against a live (i.e. running) realm, you specify the server's name as the first parameter of the tool. You can also specify which check, or checks, will be executed by using the check's name, or list of checks, as the second parameter.
An example of HealthChecker live analysis is:
runUMTool HealthChecker -rname=<rname>
-check=checkname1,checkname2,...
In this way, the tool will execute the specified checks on the realm specified by -rname. Two considerations are important here:
1. If -check is not present, all the checks will be executed by default;
2. If the realm is a node of the cluster, the checks will also be automatically executed against all the other cluster members.
XML analysis
If you want to run an offline check of the realm's configuration, you specify the XML file containing the realm's exported configuration. Also in this case it is possible to specify which check will be executed using the check's name, or a list of checks if there are more than one. An example of this second implementation is:
runUMTool HealthChecker -xml=/path/to/xml1,/path/to/xml2,...
-check=checkname1,checkname2,...
Also in this case, note the following considerations:
1. If -check is not present, then all the checks will be executed by default;
2. The -xml parameter can contain a single XML path or a list of XML paths. This is because, unlike the live analysis described above, the tool will only run the checks against all the cluster members if their XML paths are present in this list.
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.
