Collecting an agent trace dynamically using JCL

We can use the BFGAGTC member within the data set containing the JCL, for the agent that needs to be traced, to collect trace from a running Managed File Transfer for z/OS agent This can be very useful if IBM Support need to see a trace from an agent that cannot be stopped.

To collect a trace from an agent using the BFGAGTC member, complete the following steps.

Procedure

1. Locate the data set containing the JCL for the agent that needs to be traced.
2. Edit the BFGAGTC member within the data set, and locate the line that contains the text:

   -traceAgent

   The text following this contains the list of internal classes and packages that are to be traced. By default, this list is set to:

   com.ibm.wmqfte=all

   Unless otherwise specified by the IBM Support representative, leave this value as is.
3. Submit the BFGAGTC member.
4. Reproduce the issue.
5. Edit the BFGAGTC member again, and set the -traceAgent parameter to =off, as shown:

   -traceAgent =off +

6. Submit the BFGAGTC member again, to turn trace off.
7. If an agent is busy, then it is possible that the trace files will wrap quickly and overwrite the information needed to investigate the issue. In this situation there are two options:
   1. The first option is to:
      1. Schedule some time to stop the agent.
      2. Locate the agent.properties file for the agent that needs to be traced. The agent.properties file can be found in the BFG_DATA/mqft/config/coordination_qmgr_name/agents/agent_name directory.
      3. Edit the files and add entries for the following properties:
         • traceFiles=number of trace files to use
         • traceSize=size of each trace file, in MB

           The traceFiles and traceSize properties are used to control the amount of trace data that is collected.

           The default value of the traceFiles property is 5, and the traceSize property has the default value of 20MB. This means that if you turn on trace dynamically, and you have not set the properties, the agent writes trace information to 5 wrapping trace files, each with a maximum size of 20MB.

           We should set these properties to large values, to collect as much trace data as possible.

           For example, to collect 1GB of wrapping trace, add the following lines to the agent.properties file:

           traceFiles=5
           traceSize=200
           

           This results in the agent writing trace data to a maximum of 5 files, where each file has a size of 200MB.

           For more information on these agent properties, see The MFT agent.properties file.

      4. Locate the data set containing the JCL for the agent that needs to be traced.
      5. Submit the BFGAGSP member within the data set to stop the agent.
      6. Restart the agent, by submitting the BFGAGST member in the data set.
      7. Edit the BFGAGTC member within the data set, and locate the line that contains the text:

         -traceAgent

         The text following this contains the list of internal classes and packages that are to be traced. By default, this list is set to:

         com.ibm.wmqfte=all

         Unless otherwise specified by the IBM Support representative, leave this value as is.
      8. When it is time to enable trace, submit the BFGAGTC member.
      9. Reproduce the issue.
      10. Edit the BFGAGTC member again, and set the -traceAgent parameter to =off, as shown:

          -traceAgent =off +

      11. Submit the BFGAGTC member again, to turn trace off.

   2. The second option is to contact the IBM Support representative, if it is not possible to stop the agent for a short period of time. We can then discuss alternative trace specifications to use, in order to reduce the amount of trace data that is being generated.

Results