Universal Messaging 10.7 | Administration Guide | Command Line Administration Tools | The "Realm Information Collector" Diagnostic Tool
 
The "Realm Information Collector" Diagnostic Tool
Overview
RealmInformationCollector is a command-line diagnostic tool that gathers files and live data from one or more Universal Messaging realm servers. The tool makes it easier for you to collect information that Software AG support may require to diagnose issues with Universal Messaging, but the information collected may also be useful for internal support within your organization.
The tool can be executed in live and offline mode:
*Live mode: In live mode, the specified Universal Messaging realm server(s) must be running.
The tool will collect files that contain operational data for each running realm server, but will also attempt to connect to and gather information directly from each running server process.
*Offline mode: In offline mode, the specified Universal Messaging realm server(s) must be offline.
In this mode, the tool will only collect files that contain operational data for each realm server.
The mode of operation (either offline or live) is a mandatory argument and must be specified when running the tool. You must ensure that the specified Universal Messaging realm servers are stopped when -mode=offline, or running when -mode=live.
Depending on the mode, the tool will collect different files. For example, in live mode, it will not collect the content of realm server's "data" directory, because this might cause failures on the server.
The tool collects information by executing a list of collectors. Each collector is responsible for gathering a specific subset of the realm's information.
Collectors for a live realm server
The collectors that can be run against a live realm server are shown in the following table. Path names of files and directories given in the table are the installation defaults.
Name of Collector
Description
Default collector?
clientinfo
Collects client connection information from a running realm server.
consumerinfo
Collects consumer connection information from a running realm server.
env
Collects environment information from a running realm server.
This includes all JVM system properties and the list of Universal Messaging interfaces.
Y
healthchecker
Acquires health information from a running realm server using the HealthChecker tool. See the section Running a Configuration Health Check for details.
Y
heapdump
Acquires a heap dump from a running realm server.
Note:
This collector is not available on all platforms. See the section Operational Issues below for related information.
heapdumps
Collects the heap dump directory of a realm server.
The location of this directory is <InstallDir>/UniversalMessaging/server/<realmname>/heap_dumps.
See the section The Dump file for Out-of-Memory Errors (OOME) for related information about heap dumps.
installlogs
Collects the product's installation log files.
These files are located in <InstallDir>/install/logs.
Y
instancemgr
Collects the realm server's manager log.
This file is located in <InstallDir>/UniversalMessaging/tools/InstanceManager/instanceLog.txt.
Y
jaas
Collects the JAAS configuration of a realm server.
This file is located in <InstallDir>/UniversalMessaging/server/<realmname>/bin/jaas.conf.
Y
license
Collects the license file of a realm server.
This file is located in <InstallDir>/UniversalMessaging/server/<realmname>/licence.xml.
logs
Collects logs of a realm server.
The location of the file is <InstallDir>/UniversalMessaging/server/<realmname>/data/nirvana.log. If there are any rolled log files in addition to the current log file, for example nirvana.log_<timestamp1> and nirvana.log_<timestamp2>, these are collected also.
Additionally, it collects logs created by the trace logger, if present. The location of the trace logging directory is <InstallDir>/UniversalMessaging/server/<realmname>/data/traceLogging by default. If this directory is changed via the com.softwareag.um.server.log.TraceLoggerPath system property, this will also be taken into account when the Realm Information Collector is executed and the log files will be collected.
Y
migrationlogs
Collects Software AG migration logs.
osinfo
Collects operating system and hardware information. The collector will gather hardware, processor, memory, file system, and network information from the operating system. The data will be stored in the file generated/osinfo.txt in the generated archive.
The osinfo tool runs on Windows, Apple macOS, Red Hat Enterprise Linux, and Solaris operating systems.
Y
plugins
Collects the plugins directory of a realm server.
This directory is located at <InstallDir>/UniversalMessaging/server/<realmname>/plugins.
Y
psinfo
Collects information about processes in the operating system. The collector records the top 20 processes in terms of CPU consumption and stores the data in the generated/osinfo.txt file in the generated archive.
The psinfo collector runs together with the osinfo collector, which is selected by default. If you try to run psinfo without osinfo, the system returns an error.
The psinfo tool runs on Windows, Apple macOS, Red Hat Enterprise Linux, and Solaris operating systems.
Y
realmconfig
Collects the realm configuration properties of a realm server. The properties are listed in the section Realm Configuration. The collector delivers the configuration properties as a serialized XML file.
Y
secfile
Collects the security file of a realm server.
This file is located at <InstallDir>/UniversalMessaging/server/<realmname>/bin/secfile.conf.
Y
spmlogs
Collects SoftwareAG spm logs.
tanukiconf
Collects the Tanuki service wrapper configuration of a realm server.
This includes the files nserverdaemon.conf, Server_Common.conf and Custom_Server_Common.conf, located at <InstallDir>/UniversalMessaging/server/<realmname>/bin.
Y
tanukilogs
Collects Tanuki service wrapper logs of a realm server.
This file is located at <InstallDir>/UniversalMessaging/server/<realmname>/bin/UMRealmService.log. If there are any rolled log files in addition to the current log file, for example UMRealmService.log.1 and UMRealmService.log.2, these are collected also.
Y
threaddump
Generates three thread dumps of a realm server. The dumps are taken at 15-second intervals. Having three dumps instead of one can make it easier to analyze time-related thread issues.
Y
A "Y" in the column "Default collector?" indicates that the collector is included by default when you run the RealmInformationCollector tool.
Collectors for an offline realm server
The collectors that can be run against an offline realm server are the following (collectors that can be used also against a live realm server are indicated). Path names of files and directories given in the table are the installation defaults.
Name of Collector
Description
Default collector?
data
Collects the data directory of a realm server.
The location of this directory is <InstallDir>/UniversalMessaging/server/<realmname>/data.
heapdumps
(Same as the live collector)
installlogs
(Same as the live collector)
Y
instancemgr
(Same as the live collector)
Y
jaas
(Same as the live collector)
Y
license
(Same as the live collector)
logs
(Same as the live collector)
Y
migrationlogs
(Same as the live collector)
osinfo
(Same as the live collector)
Y
plugins
(Same as the live collector)
Y
psinfo
(Same as the live collector)
Y
secfile
(Same as the live collector)
Y
spmlogs
(Same as the live collector)
tanukiconf
(Same as the live collector)
Y
tanukilogs
(Same as the live collector)
Y
version
Collects the realm server version from a non-running UM server instance. The version will be stored in the file UniversalMessaging/lib/nServer.jar_version.txt in the generated archive.
Command Usage
The syntax is as follows:
runUMTool RealmInformationCollector
-mode=live|offline [-username=<username> -password=<password>]
-instance=*|<instanceName>[,<instanceName> ...]
[-include=<collectorName>[,<collectorName> ...] ]
[-exclude=<collectorName>[,<collectorName> ...] ]
[-outputfile=<dir_or_file>]
[-logsduration=<duration>]
Displaying help text
To display a help text showing a summary of the command usage, call the RealmInformationCollector tool without parameters:
runUMTool RealmInformationCollector
The -mode parameter
This parameter allows you to select the execution mode of the tool. The mode parameter is mandatory and can take one of the following values:
*live - the RealmInformationCollector tool will collect operational data files for each running realm server and also attempt to connect and gather information directly from each running realm server
*offline - the tool will collect operational data files only
In live mode, all specified realm servers (see the -instance parameter) must be running, whereas in offline mode, all specified realm servers must be stopped.
Also in live mode, the following collectors will connect to each specified running realm server to gather information, and will store the information in the following files under UniversalMessaging/server/<InstanceName>/generated in the generated archive:
Collector name
Generated file
env
envinfo.txt
realmconfig
RealmConfig.xml
healthchecker
healthchecker.txt
threaddump
Three thread dump files, generated at 15-second intervals, named threaddump_<timestamp>.txt
The -username and -password parameters
When establishing the connection to a live realm server, the RealmInformationCollector tool will authenticate using the current operating system user. It is therefore recommended to run the RealmInformationCollector tool using the same user as the one used to run the realm server.
You can specify a different user using the -username and -password arguments.
The -instance parameter
This parameter allows you to select the set of realm servers to collect information from. The parameter is mandatory and must contain either a single realm server name or a comma-separated list of realm server names. The specified realm servers must be available in the installation where the RealmInformationCollector tool is run from. You can specify -instance=* to select all installed realm servers.
The -include and -exclude parameters
You can use the -include and -exclude parameters to further refine the set of collectors that have been selected by the -mode parameter. You can use -include and -exclude in the same call of the RealmInformationCollector tool as long as they do not specify the same collector name.
*include - Run all default collectors available with the specified -mode parameter, and additionally include the collector or collectors specified by this parameter. The parameter may contain a single collector name or a comma-separated list of collector names.
*exclude - Run all default collectors available with the specified -mode parameter, except the specified collector or collectors. The parameter may contain a single collector name or a comma-separated list of collector names.
The -outputfile parameter
Specifies the path where the generated zip archive will be stored.
If the path specifies a directory without a filename, the directory must already exist. The archive file will be generated in the specified directory using the following naming convention:
<InstallDir>_<mode>_<timestamp>.zip
For example, if the product installation directory is C:\SoftwareAG and the RealmInformationCollector tool is executed with -mode=live, the generated archive will be named for example SoftwareAG_live_20171120100757940.zip
If the path specifies a directory with a filename, the directory must already exist but the file must not already exist, and the tool will use the filename you specify.
If the parameter is not specified, the tool will generate an archive with a name corresponding to the naming convention mentioned above, and store the archive under the directory <InstallDir>/UniversalMessaging/tools/runner.
The -logsduration parameter
Specifies the age of the oldest log that is to be returned, relative to the current time. The age can be specified in days or hours or both.
For example, if the logs are required for the past 2 days and 4 hours, the option can be specified as:
-logsduration=2d4h
Syntax Examples
Example: Execute default collectors in offline mode against the umserver instance:
runUMTool RealmInformationCollector -mode=offline -instance=umserver
Example: Execute default collectors and also optional collectors data and heapdumps in offline mode against the umserver instance:
runUMTool RealmInformationCollector
-mode=offline -instance=umserver -include=data,heapdumps
Example: Execute default collectors and the optional collectors data and heapdumps, excluding the jaas collector, in offline mode against all realm server instances:
runUMTool RealmInformationCollector
-mode=offline -instance=* -include=data,heapdumps -exclude=jaas
Example: Execute default collectors in live mode against the umserver instance:
runUMTool RealmInformationCollector -mode=live -instance=umserver
Example: Execute the default collectors and optional collectors heapdump and heapdumps in live mode against the umserver instance:
runUMTool RealmInformationCollector
-mode=live -instance=umserver -include=heapdump,heapdumps
Example: Execute the default collectors and optional collectors heapdump and heapdumps, excluding the jaas collector, in live mode against the umserver and umserver2 instances:
runUMTool RealmInformationCollector
-mode=live -instance=umserver,umserver2 -include=heapdump,heapdumps -exclude=jaas
Example: Execute the default collectors and optional collectors heapdump and heapdumps in live mode against the umserver instance and specify a custom location of the generated zip archive:
runUMTool RealmInformationCollector
-mode=live -instance=umserver -include=heapdump,heapdumps
-outputfile=C:/SoftwareAG_umserver_live.zip
Example: Execute default and logs collectors in live mode against all realm servers and collect logs for a specific duration:
runUMTool RealmInformationCollector
-mode=live -instance=* -include=logs -logsDuration=2d4h
Example: Execute default and clientinfo and consumerinfo collectors in live mode against the umserver server instance:
runUMTool RealmInformationCollector
-mode=live -instance=umserver -include=clientinfo,consumerinfo
Operational Issues
*On Windows, if the product installation directory path is too long, acquiring a live heap dump may fail with the error "CreateProcess error=267, The directory name is invalid". You can work around this error by configuring the -outputFile parameter to use a shorter directory/file path, for example C:/SoftwareAG_live.zip.
*The RealmInformationCollector tool does not support connecting via SSL-secured network interfaces to the realm server. If all realm server network interfaces are secured using SSL, live collectors which need to connect to the server (env, realmconfig, healthchecker, threaddump) will fail to connect to the server. You can work around this by configuring a temporary non-SSL secured network interface.
*Live heap dump generation using the heapdump collector is only available with the JVM that is delivered with the Universal Messaging distribution kit on Windows and Solaris machines. This feature is currently not available for use with other JVMs.
*The RealmInformationCollector tool might fail to acquire a live heap dump if the tool run with a different operating system user than the one used for running the realm server. It is recommended to run the tool with the same operating system user that was used to run the realm server.