Tracing the REST API

The trace facilities in the REST API are provided to help IBM staff to diagnose customer problems. Various properties control the behavior of these facilities.


Before starting

Include the following files and directories when you gather diagnostic information for IBM Service:

  • The mqweb.xml file.
  • The contents of the directory that contains the mqweb server definition:

    • MQ_DATA_PATH/web/installations/installationName
    • The directory that was specified when the crtmqweb script ran to create the mqweb server definition. By default, this directory is /var/mqm/web/installation1.


The REST API consists of two functional areas, each with their own trace mechanisms:

  • Enable trace for the REST API code that runs in the mqweb server
  • Enable messaging trace for the REST API code that runs in the mqweb server.

For information about enabling trace for the IBM MQ Console, see:


Procedure

  1. Enable trace for the REST API code that runs in the mqweb server
    1. Enter the following command on the command line: 
      setmqweb properties -k traceSpec -v "*=info:com.ibm.mq*=all:com.ibm.mq.rest*=all:js.mq*=all"

    If the mqweb server is running, trace is immediately enabled.

    Trace is output to a set of files. The directory where the trace files are created is:

    • MQ_DATA_PATH/web/installations/installationName/servers/mqweb/log
    • The subdirectory /servers/mqweb/log beneath the directory that was specified when the crtmqweb script ran to create the mqweb server definition. By default, this directory is /var/mqm/web/installation1.

    The active file is called trace.log. Historical trace is kept in files that are called trace_timestamp.log. The size of these trace files, and the number of historical files that are kept can be configured by setting the maxTraceFileSize and maxTraceFiles variables. By default, the maximum trace file size is 20 MB, and the maximum number of trace files is 2. For more information, see Configure logging.

  2. Enable messaging trace for the REST API code that runs in the mqweb server
    1. Create a file called jmstrace.config in one of the following directories:

      MQ_DATA_PATH/web/installations/installationName/servers/mqweb

      WLP_user_directory/servers/mqweb

      Where WLP_user_directory is the directory that was specified when the crtmqweb script ran to create the mqweb server definition.

    2. Add the following lines to the jmstrace.config file: 
      com.ibm.msg.client.commonservices.trace.outputName=PATH/logs/jmstrace.txt
com.ibm.msg.client.commonservices.trace.limit=104857600
com.ibm.msg.client.commonservices.trace.count=10
com.ibm.msg.client.commonservices.trace.status=ON

      Where PATH specifies the full path to the directory where we want the jmstrace.txt file to be written.

      These lines set the maximum trace file size to 100 MB, and set the maximum number of trace files to 10. Ensure that we have disk space available for these files.

    3. In the same directory as the jmstrace.config file, open or create the jvm.options file.
    4. Add the following lines to the jvm.options file: 
      -Dcom.ibm.msg.client.commonservices.trace.startup=TRUE
-Dcom.ibm.msg.client.config.location=CONFIG_PATH/jmstrace.config

      Where CONFIG_PATH specifies the full path to the directory where the jmstrace.config file is located, as a URL. For example, file:c:/ProgramData/IBM/MQ/web/installations/Installation2/servers/mqweb/.

    5. Restart the mqweb server by using the following commands on the command line: 
      endmqweb
strmqweb

Parent topic: Use trace