IBM Support

Using the IBM MQ runmqras command to collect diagnostic data

Question & Answer


Question

How do I use runmqras to collect IBM MQ diagnostic data?

Answer

 
 

Starting runmqras

The runmqras command is a Java™️ application for collecting IBM MQ diagnostic data. If your IBM MQ installation includes the Java JRE component runmqras will use it, otherwise make sure a recent Java runtime environment (JRE) is in your PATH to avoid the error AMQ8599E: The runmqras command was unable to locate a JRE. Before using runmqras you may wish to clean up MQ files to reduce the amount of data collected.

Ensure your environment is set up for your IBM MQ installation before starting runmqras. For example:

Setting the MQ environment on Linux and UNIX

sh> PATH="$PATH":/path/to/java/bin (only if needed)

sh> . /opt/mqm/bin/setmqenv ‑n Installation1

Setting the MQ environment on Windows

C:\> SET PATH=%PATH%;C:\path\to\java\bin; (only if needed)

C:\> C:\Program Files\IBM\MQ\bin\setmqenv ‑n Installation2

Setting the MQ environment on IBM i (Qshell)

Use the latest available IBM Java runtime on your IBM i system. For example:

===> PATH="$PATH":/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit (only if needed)

 

Optionally, you can add the /QIBM/ProdData/mqm/bin directory to your PATH so you can use runmqras without typing its full path. To do so, enter one of the following commands in the Qshell or add it to the .profile file in your home directory so it will run automatically every time you start the Qshell.

===> . /QIBM/ProdData/mqm/bin/setmqenv -s (IBM MQ 8.0 and later)

===> PATH="$PATH":/QIBM/ProdData/mqm/bin (WebSphere MQ 7.5 and earlier)


 

Collecting data for a case

IBM MQ has joined the new Support Community which uses cases rather than problem management records to track issues. Case numbers like TS123456789 have replaced PMR numbers like 12345,678,999.

If you are running IBM MQ 9.1.1 CD, 9.1.0.1 LTS, 9.0.0.5 LTS, 8.0.0.10, WebSphere MQ 7.5.0.9, or any later version, the runmqras command can create a zip file ready to upload to your IBM case. For example:

Setting the case number on Linux and UNIX

sh> runmqras ‑caseno TS123456789

Setting the case number on Windows

C:\> runmqras ‑caseno TS123456789

Setting the case number on IBM i (Qshell)

===> /QIBM/ProdData/mqm/bin/runmqras ‑caseno TS123456789

 
 

If you are running an older version of MQ, use the ‑zipfile option instead of the ‑caseno option to make the output file name start with your case number. For example:

Setting the case number in older MQ versions on Linux and UNIX

sh> runmqras ‑zipfile TS123456789

Setting the case number in older MQ versions on Windows

C:\> runmqras ‑zipfile TS123456789

Setting the case number in older MQ versions on IBM i (Qshell)

===> /QIBM/ProdData/mqm/bin/runmqras ‑zipfile TS123456789

 
 

Choosing sections to gather

The runmqras command uses a configuration file called isa.xml which describes which files to collect and which commands to run. This file is organized into sections which identify the information to solve different kinds of problems, and IBM adds new sections as needed.

IBM support or the IBM MustGather documentation will tell you which sections to gather for each kind of problem. For example:

Choosing sections on Linux and UNIX

sh> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace

Choosing sections on Windows

C:\> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace

Choosing sections on IBM i (Qshell)

===> /QIBM/ProdData/mqm/bin/runmqras ‑caseno TS123456789 ‑section defs,cluster,trace

 

Choosing queue managers

By default the runmqras command tries to collect information about all queue managers. Use the ‑qmlist option to provide a comma-separated list of queue managers in your current installation which runmqras should examine. Do not use the ‑qmlist option on MQ client installations.

If you have multiple MQ installations, don't use the runmqras command from one installation to collect information about a queue manager in a different installation. While the runmqras command will not fail outright, some of the commands issued by runmqras will fail with the error AMQ6292: The queue manager is associated with a different installation.

Instead, use the setmqenv command to switch between installations. In each installation use the ‑qmlist option to collect information from the queue managers associated with that installation.

The queue managers you choose should be running, or else some the commands issued by runmqras will fail with the error AMQ8146: IBM MQ queue manager not available. However, the runmqras command is still useful if you have a queue manager which you cannot start.

Choosing queue managers on Linux and UNIX

sh> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace ‑qmlist QMA,QMB,QMC

Choosing queue managers on Windows

C:\> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace ‑qmlist QMA,QMB,QMC

Choosing queue managers on IBM i (Qshell)

===> /QIBM/ProdData/mqm/bin/runmqras ‑caseno TS123456789 ‑section defs,cluster,trace ‑qmlist QMA,QMB,QMC

 
 

Handling large files

The zip archive created by runmqras can be very large if your system has lots of FDCs or trace files to collect, or if you collect the all or QMGR sections. Normally runmqras uses space in a temporary directory to collect and zip up the files.

To choose a different directory on a file system or disk with more free space, use the -workdirectory> option. The directory you give must be empty. If it does not exist yet, runmqras will create it. For example:

Handling large files on Linux and UNIX

sh> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace,QMGR ‑qmlist QMA,QMB,QMC ‑workdirectory /var/bigdata/2019‑07‑27

Handling large files on Windows

C:\> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace,QMGR ‑qmlist QMA,QMB,QMC ‑workdirectory G:\BigData\2019‑07‑27

Handling large files on IBM i (Qshell)

===> /QIBM/ProdData/mqm/bin/runmqras ‑caseno TS123456789 ‑section defs,cluster,trace,QMGR ‑qmlist QMA,QMB,QMC ‑workdirectory /QIBM/bigdata/2019‑07‑27


 

Sending data to IBM

The runmqras command provided options to upload the file directly to IBM using standard (non-SSL) FTP. Due to data protection requirements, those options should no longer be used.

Make sure the runmqras zip file starts with your IBM case number, for example TS123456789‑runmqras.zip. Then send the file to IBM using any of the methods described here.

Blue Diamond clients must use the secure Blue Diamond upload instead.

 
 

Cleaning up files

The runmqras command does not delete any files from your system, neither MQ logs, nor FDCs, job logs, dumps, or trace files. After collecting these files with runmqras, IBM recommends that you archive or delete your FDCs, job logs, dumps and trace files. If you need to collect runmqras at a later time, the new runmqras file will be smaller and easier to analyze because it does not contain duplicate files and old information.

Keep a copy of your runmqras zip file after sending it to IBM until your problem is resolved and you have tested the solution to your satisfaction.


 

Section reference

This is the canonical list of runmqras sections showing a description, the platforms where the section is supported, and the versions of MQ where the section is available. Unrecognized sections are ignored by runmqras, so there is no error if you include a section name which is not supported on your platform or version:

Section Description Platform Availability
all Collects all sections, including the entire queue manager (very large)
Use this option only when specifically requested by IBM support!
AIX, HP-UX, IBM i, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5, 7.1.0.1, 7.0.1.8
default Collects basic MQ and system information (always included by default) AIX, HP-UX, IBM i, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5, 7.1.0.1, 7.0.1.8
nodefault Prevents the default section from being collected AIX, HP-UX, IBM i, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5, 7.1.0.1, 7.0.1.8
defs Collects MQ definitions and status AIX, HP-UX, IBM i, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5, 7.1.0.1, 7.0.1.8
cluster Collects MQ cluster information AIX, HP-UX, IBM i, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5, 7.1.0.1, 7.0.1.8
trace Collects MQ trace files which you have generated AIX, HP-UX, IBM i, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5, 7.1.0.1, 7.0.1.8
dap Collects internal information about MQ object storage AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5.0.1, 7.1.0.1, 7.0.1.9
kernel Collects internal information about the MQ kernel AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5.0.1, 7.1.0.1, 7.0.1.9
logger Collects information about the MQ logger AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5.0.1, 7.1.0.1, 7.0.1.9
topic Collects information about the MQ publish/subscribe topic tree AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5.0.1, 7.1.0.1, 7.0.1.9
QMGR Collects the entire queue manager (very large)
Use this option only when specifically requested by IBM support!
AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5.0.2, 7.1.0.3, 7.0.1.11
format Formats the MQ trace files (should be used with the trace section) AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0, 7.5.0.2, 7.1.0.3, 7.0.1.11
webui Collects web UI information MQ Appliance 9.1 CD, 9.1 LTS, 9.0 LTS, 8.0.0.3
mft Collects Managed File Transfer information AIX, HP-UX, IBM i, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0.0.3, 8.0.0.8, 7.5.0.9
leak Collects information about memory usage and leaks AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris 9.1 CD, 9.1 LTS, 9.0.0.3, 8.0.0.9, 7.5.0.9
environ Collects information about the environment AIX, Linux, macOS, MQ Appliance, Solaris 9.1 CD, 9.1 LTS, 9.0.0.3, 8.0.0.9, 7.5.0.9
cs Collects MQ common services information AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0.1 CD
selector Collects information about MQ selectors AIX, HP-UX, Linux, macOS, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0.1 CD
mqweb Collects web UI information AIX, HP-UX, Linux, MQ Appliance, Solaris, Windows 9.1 CD, 9.1 LTS, 9.0.4 CD
san Collects SAN information MQ Appliance 9.1 CD, 9.1 LTS, 9.0.4 CD
application Collects information about applications AIX, HP-UX, IBM i, Linux, macOS, MQ Appliance, Solaris, Windows 9.1.2 CD

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSYHRD","label":"IBM MQ"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF031","label":"Ubuntu"},{"code":"PF033","label":"Windows"}],"Version":"9.1;9.0;8.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SS5K6E","label":"IBM MQ Appliance"},"Component":"","Platform":[{"code":"PF004","label":"Appliance"}],"Version":"9.1;9.0;8.0","Edition":"","Line of Business":{"code":"LOB36","label":"IBM Automation"}},{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSFKSJ","label":"WebSphere MQ"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"7.5;7.1;7.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
30 July 2019

UID

swg21624944