Universal Messaging 9.10 | Administration Guide | Command Line Administration Tools | Collecting Realm Information
 
Collecting Realm Information
Overview
RealmInformationCollector is a command-line tool that gathers files and live data from one or more Universal Messaging realm servers. 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?
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 using the jmap tool that is available in the Oracle-based JDK included in the Universal Messaging distribution kit.
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.
Y
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.
Y
plugins
Collects the plugins directory of a realm server.
This directory is located at <InstallDir>/UniversalMessaging/server/<realmname>/plugins.
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
tanukiconf
Collects the Tanuki service wrapper configuration of a realm server.
This includes the files nserver.conf, 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
version
Collects the realm server version. The version will be stored in the file UniversalMessaging/lib/nServer.jar_version.txt in the generated archive.
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.
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)
Y
logs
(Same as the live collector)
Y
plugins
(Same as the live collector)
Y
secfile
(Same as the live collector)
Y
tanukiconf
(Same as the live collector)
Y
tanukilogs
(Same as the live collector)
Y
version
(Same as the live collector)
Y
Command Usage
The syntax is as follows:

runUMTool RealmInformationCollector
-mode=live|offline
-instance=*|<instanceName>[,<instanceName> ...]
[-include=<collectorName>[,<collectorName> ...] ]
[-exclude=<collectorName>[,<collectorName> ...] ]
[-outputfile=<dir_or_file>]
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 -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 -output 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.
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 the optional collector data in offline mode against the umserver instance:

runUMTool RealmInformationCollector
-mode=offline -instance=umserver -include=data
Example: Execute default collectors and the optional collector data, excluding the jaas collector, in offline mode against all realm server instances:

runUMTool RealmInformationCollector
-mode=offline -instance=* -include=data -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 the optional collector heapdump in live mode against the umserver instance:

runUMTool RealmInformationCollector
-mode=live -instance=umserver -include=heapdump
Example: Execute the default collectors and the optional collector heapdump, excluding the jaas collector, in live mode against the umserver and umserver2 instances:

runUMTool RealmInformationCollector
-mode=live -instance=umserver,umserver2 -include=heapdump -exclude=jaas
Example: Execute the default collectors and the optional collector heapdump 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
-outputfile=C:/SoftwareAG_umserver_live.zip
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 is available with the Oracle-based JVM only.
*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.
Copyright © 2013-2019 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.