Gathering JVM diagnostics with the PERFORM JVMSERVER SPI

The PERFORM JVMSERVER (jvmserver) JVM GATHER DIAGNOSTICS command (the GATHER SPI) collects useful JVM server diagnostic information, aggregating multiple existing trace, dump, log and configuration files into a single tar file. On request, you can send this file to IBM®'s service teams when they are helping you with JVM server problems.

Gathering diagnostics

Note that this command does not initiate the generation of any new trace, dump log or configuration files - it aggregates existing files into a single output tar file. The PERFORM JVMSERVER(jvmserver) JVM GATHER DIAGNOSTICS command runs asynchronously for a specific JVM server. When running, it holds a lock, so that identical commands for the same JVM server are refused until the first command is complete and its lock released.

The name of the generated file corresponds to the pattern <applid>-<jvmserver>-<timestamp>-diags.tar, where applid is the APPLID of the relevant CICS® system and jvmserver is the name of the targeted JVM server.

The output file is by default stored in the JVM server's WORK_DIR/diagnostics/archives folder, but you can override this location by setting an alternative DIAGS_ARCHIVE_DIR in the JVM profile. Override DIAGS_TEMP_DIR in the JVM profile to specify a preferred location for a folder that contains temporary trace files, otherwise these are stored in /tmp. Finally, you can override SCRIPT_TIMEOUT_SECS, which defaults to 300 seconds and specifies the number of seconds the command is permitted to run before it is considered to have malfunctioned, whereupon execution is abandoned and any running process terminated.

Check the MSGUSR logs for an entry that specifies the location of the generated tar file, or - if the command fails - the location of a trace file containing error information.

Note: Check the MSGUSR log file for related progress messages:
  • DFHSJ0928: Starting to gather diagnostics
  • DFHSJ0936: GATHER DIAGNOSTICS completed OK
  • DFHSJ0937: GATHER DIAGNOSTICS failed

The first lines of the trace file contain a list of the files gathered, and note the circumstances under which they were gathered. Run the command and review the trace file for more information. If the command worked, the trace file is contained within the generated tar file. If it failed, the trace file is left in the temporary folder described previously.

Prior to sending the generated tar file to IBM's service team, it is recommended that you review its contents to ensure that you are comfortable sending this information, and that it does not contravene any of your organizational policies.