Gathering diagnostic data

You use the automated utility MustGather Diagnostic Tool to collect diagnostic data from Decision Runtime for z/OS environments.

Before you begin

You must have the following items to run MustGather:

Decision Runtime for z/OS environment that is configured and operational
Working datasets that are allocated and accessible
All supporting environments are installed and configured, for example, JAVA_HOME and DB2
Read access to the following resources:
- Target datasets (TLIB)
- Working datasets (WORKDS)
- USS directories (HBRWORKPATH, HBRINSTPATH)
- SDSF job outputs
Write permission to the USS temporary directory.
Sufficient USS space for temporary files and a compressed archive (.zip) for MustGather results.

About this task

MustGather obtains the following content and places it in a compressed archive that the user can give to IBM Support to resolve problems:

Table 1. MustGather data
Area	Description	Examples
USS logs	Runtime and trace logs	HBRSSID-runtime-0.log, messages.log, and trace.log
XML files	Configuration files	server.xml and bootstrap.properties
Dataset members	SHBRPARM datasets	HBRINST, HBRCTRL, HBRMSTR, HBRCMMN, HBRPSIST, and HBREMBED
Job outputs	SDSF job logs	{SSID}MSTR, HBRMINB, HBRMINBP, HBRMINBE, and HBRMINBJ

Key benefits:

Ensuring complete data collection
Providing consistent output across environments
Reducing collection time from hours to minutes
Automatically obfuscating sensitive data
Producing a single, shareable archive

MustGather is used to obtain diagnostic data for the following problems:

Production outages
Performance issues
Configuration problems
Upgrade failures
Integration troubleshooting

MustGather is available in Decision Runtime for z/OS 9.5 and later.

Procedure

Validate the values in ++HBRWORKDS++.SHBRJCL(HBRSUPRT):
```
PARAMETERS="/tmp/mustGather.zip +                          

        SDSFJOBNAME=SDSFOUT DELETEJOBNAME=DELETE"    
        
```
If necessary, do the following:
- Change the output file location if required.
- Choose a SDSF job name that complies to your site rules
- Choose a delete job name that complies to your site rules
Note: SDSFOUT collects job output into temporary datasets, which are copied to USS; a DELETE job then removes the temporary datasets.
Submit the job.
Monitor the execution.
Check SYSOUT for:
- Properties being read
- Topologies being processed
- Files and SDSF jobs being collected
- Compressed archive (.zip) creation status
Copy the compressed file /tmp/mustGather.zip from the mainframe to your laptop.

Extract and review the contents of the file:

mustGather.zip /
├── Jobs_Members/
│   ├── ZRES/
│   │   ├── SSID1/
│   │   │   ├── HBR.TLIB.SHBRPARM_HBRINST
│   │   │   ├── HBR.WORK.SHBRPARM_HBRMSTR
│   │   │   ├── SSID1MSTR_1.txt  (latest five occurrence)
│   │   │   └── HBRMINB_1.txt (latest five occurrence)
│   │   └── SSID2/
│   │   └── ...
│   ├── CICS/
│   │   └── CICSRGN1/
│   │   └── ...
│   └── BATCH/
│   │   └── ...
│   └── .../
│       └── ...
├── Logs_And_XML/
│   ├── SSID1(ZRES)/
│   │   ├── logs/
│   │   │  ├── SSID(ZRES)-runtime-0.log
│   │   │   └── SSID(CONSOLE)-runtime-0.log
│   │   │   └── ...
│   │   ├── config/
│   │   │   └── res/console (.properties/ra.xml)
│   │   └── ...
│   └── SSID2(CONSOLE)/
│   │   |-servers/ 
│   │      └── SSID(CONSOLE)
│   │         └── logs
│   │            └── .xml/bootstrap.properties
│   │            └── ...
│   └── .../
│      └── ...│
└── FileStatusReport.txt (also copied outside ZIP)

Share the file with IBM Support.

Results

The MustGather tool uses the configuration details in HBRINST and HBRCTRL before the submission of HBRINST. Ensure your configuration stays accurate in those members. If your installation diverges from those values, you might have to gather additional content for IBM Support.