Tracing the REST API

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

Before you begin

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

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.

About this task

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

Trace for the REST API code that runs in the mqweb server.
Messaging trace for the REST API code that runs in the mqweb server.

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

Procedure

Enabling 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/logs
- The subdirectory /servers/mqweb/logs 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 Configuring logging.
Enabling 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 you 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 you 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
```