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 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 a 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.
diagnostics	Collects diagnostics of a running realm server and stores them in a diagnostics.txt file. The location of the file is `<InstallDir>/UniversalMessaging/server/instanceName/generated/diagnostics.txt`. The diagnostics include channel, cluster, and thread information about the realm, and the log header of the realm.	Y
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/instanceName/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. The location of the files is `<InstallDir>/install/logs`.	Y
instancemgr	Collects the realm server's manager log. The location of the file is `<InstallDir>/UniversalMessaging/tools/InstanceManager/instanceLog.txt`.	Y
jaas	Collects the JAAS configuration of a realm server. The location of the file is `<InstallDir>/UniversalMessaging/server/instanceName/bin/jaas.conf`.	Y
jmxexporter	Collects the jmx_sag_um_exporter.yaml file, the configuration file of the Prometheus JMX exporter agent. The location of the file is `<InstallDir>/UniversalMessaging/server/instanceName/bin/jmx_sag_um_exporter.yaml`.	Y
logs	Collects the following logs: The logs of a realm server. The location of the file is `<InstallDir>/UniversalMessaging/server/instanceName/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. The logs created by the trace logger, if present. The location of the trace logging directory is `<InstallDir>/UniversalMessaging/server/instanceName/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. The log files configured through file appenders inside the log4j2.xml configuration file. The Realm Information Collector obtains the location of the files using the `fileName` property, which can take both absolute and relative paths. The root of the relative path is `<InstallDir>/UniversalMessaging/server/instanceName/bin`. The collected files are archived in `<RealmInformationCollector.tmp>/UniversalMessaging/server/instanceName/bin`. Any rolled log files of type `logname.extension` where '' stands for any characters following `logname.extension`.	Y
log4j2conf	Collects the log4j2.xml configuration file. The location of the file is `<InstallDir>/UniversalMessaging/lib/classes/log4j2.xml`. The collected files are archived in `<RealmInformationCollector.tmp>/UniversalMessaging/lib/classes`. The Realm Information Collector obtains the log4j2.xml configuration even when an absolute path is configured for the file in the Server_Common.conf file.	Y
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. The location of the directory is `<InstallDir>/UniversalMessaging/server/instanceName/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. The location of the file is `<InstallDir>/UniversalMessaging/server/instanceName/bin/secfile.conf`.	Y
spmlogs	Collects Platform Manager logs.
tanukiconf	Collects the Java 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/instanceName/bin`.	Y
tanukilogs	Collects Java Service Wrapper logs of a realm server. The location of the file is`<InstallDir>/UniversalMessaging/server/instanceName/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 as well. You can obtain the Java Service Wrapper logs even when you configured an absolute file path for the `wrapper.logfile` property in the Server_Common.conf file.	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
logs	(Same as the live collector)	Y
log4j2conf	(Same as the live collector)	Y
log4j2logs	(Same as the live collector)	Y
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
diagnostics	`diagnostics.txt`
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

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:/UM_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:/UM_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.