Collecting troubleshooting information automatically with runmqras

If you need to send IBM® MQ troubleshooting information to IBM Support, you can use the runmqras command to gather the information together into a single archive.

Before you begin

The runmqras command is a Java application for collecting IBM MQ troubleshooting information. 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 following error:

AMQ8599E: The runmqras command was unable to locate a JRE

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

On UNIX and Linux®:

sh> PATH="$PATH":/path/to/java/bin (only if needed)
sh> . /opt/mqm/bin/setmqenv ‑n Installation1

On Windows:

C:\> SET PATH=%PATH%;C:\path\to\java\bin; (only if needed)
C:\> C:\Program Files\IBM\MQ\bin\setmqenv ‑n Installation2

On IBM i (Qshell):
```
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
```

If you are unable to use the runmqras tool to collect the information automatically, for example if you are running an older version of IBM MQ or cannot use runmqras for any other reason, you can instead collect the information manually as described in Collecting troubleshooting information manually.

Tip: Before using runmqras, you might wish to clean up IBM MQ files to reduce the amount of data collected. For more information, see Cleaning up IBM MQ files.

About this task

You can use the runmqras command to gather troubleshooting information about an application or IBM MQ failure into a single archive that you can submit to IBM when you report a problem.

By default, runmqras gathers information such as:

IBM MQ FDC files.
Error logs (from all queue managers as well as the machine-wide IBM MQ error logs).
Product versioning, status information, and output from various other operating system commands.

If IBM Support ask you for more detailed information, you can add this by specifying the required options with the -section parameter.

Procedure

To specify that the output file name starts with your case number, use the -caseno parameter.
For example:
- On UNIX and Linux:
```
sh> runmqras ‑caseno TS123456789
```
- On Windows:
```
C:\> runmqras ‑caseno TS123456789
```
- On IBM i (Qshell):
```
/QIBM/ProdData/mqm/bin/runmqras ‑caseno TS123456789
```
If you are using an earlier version of the product that does not support the -caseno parameter , use the ‑zipfile option instead of the ‑caseno option to make the output file name start with your case number.
- On UNIX and Linux:
```
sh> runmqras ‑zipfile TS123456789
```
- On Windows:
```
C:\> runmqras ‑zipfile TS123456789
```
- On IBM i (Qshell):
```
/QIBM/ProdData/mqm/bin/runmqras ‑zipfile TS123456789
```
Choose the sections that you want to gather data for.
The runmqras command uses a configuration file called isa.xml that describes which files to collect and which commands to run. This file is organized into sections that identify the information needed to solve different kinds of problems, and IBM adds new sections as needed.
To choose the required sections, specify the -section parameter with the appropriate options. For example:
- On UNIX and Linux:
```
sh> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace
```
- On Windows:
```
C:\> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace
```
- On IBM i (Qshell):
```
/QIBM/ProdData/mqm/bin/runmqras ‑caseno TS123456789 ‑section defs,cluster,trace
```
Choose the queue managers that you want to gather data for.
By default the runmqras command tries to collect information about all queue managers. Use the ‑qmlist option to provide a comma-separated list of the queue managers in your current installation that runmqras should examine. For example:
- On UNIX and Linux:
```
sh> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace ‑qmlist QMA,QMB,QMC
```
- On Windows:
```
C:\> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace ‑qmlist QMA,QMB,QMC
```
- On IBM i (Qshell):
```
===> /QIBM/ProdData/mqm/bin/runmqras ‑caseno TS123456789 ‑section defs,cluster,trace ‑qmlist QMA,QMB,QMC
```
Important: Do not use the ‑qmlist option on IBM MQ client installations.
If you have multiple IBM MQ installations, do not 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, first use the setmqenv command to switch between installations. Then, in each installation, use the ‑qmlist option of the runmqras command 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 the runmqras command 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 that you cannot start.
Choose a different directory for handling large files.
If your system has lots of FDCs or trace files to collect, or if you collect the all or QMGR sections, the archive that the runmqras command creates can be very large. 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 that you specify must be empty. If it does not exist yet, runmqras will create it. For example,:
- On UNIX and Linux:
```
sh> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace,QMGR ‑qmlist QMA,QMB,QMC ‑workdirectory /var/bigdata/2019‑07‑27
```
- On Windows:
```
C:\> runmqras ‑caseno TS123456789 ‑section defs,cluster,trace,QMGR ‑qmlist QMA,QMB,QMC ‑workdirectory G:\BigData\2019‑07‑27
```
- 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
```
Send the troubleshooting information that you have collected to IBM Support.

Make sure that the runmqras archive file starts with your IBM case number, for example TS123456789‑runmqras.zip then send the file to IBM. For more information, see Sending troubleshooting information to IBM..

What to do next

Important: After sending your runmqras archive file to IBM, keep a copy of it until your problem is resolved and you have tested the solution to your satisfaction.

The runmqras command does not delete any files from your system, neither IBM MQ logs, nor FDCs, job logs, dumps, or trace files. After collecting these files with runmqras, consider archiving or deleting them as described in Cleaning up IBM MQ files. If you then need to collect troubleshooting information with runmqras again 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.