[MQ 9.4.0 Jun 2024]

Tracing XMS .NET applications with mqclient.ini

From IBM® MQ 9.4.0, you can use the mqclient.ini file to enable traces for the XMS .NET client libraries.

About this task

From IBM MQ 9.4.0, the mqclient.ini file includes a Trace stanza. To enable trace, you must set the appropriate properties of the Trace stanza. If a property is set to an invalid value, then the properties are ignored.

You can also enable and disable tracing dynamically. When the application is running, if the mqclient.ini file is modified, created, or deleted, the XMS .NET client reads the properties of the trace section again and then enables or disables the trace, so that restart of the application is not needed.

Note: There are several different ways to enable trace.
For the XMS .NET client libraries built against .NET Framework, the order of precedence is as follows:
  1. App.Config
  2. Environment variable
  3. mqclient.ini
For the XMS .NET client libraries built against .NET Standard and .NET 6, the order of precedence is as follows:
  1. Environment variable
  2. mqclient.ini

Procedure

  • To start trace, specify the following attributes of the Trace stanza:
    1. Set XMSDotnetTraceLevel to the value corresponding to the level of tracing you want.
      If you want to start tracing with an advanced format, set this attribute to 2. If you want to start tracing with a basic format, set the attribute to 1.
    2. Set XMSDotnetTraceFilePath to the file path of the folder where you want the trace files to be created.
      For example: XMSDotnetTraceFilePath="c:\somepath". The current directory of the application is used if the path is left blank or if the XMSDotnetTraceFilePath attribute is not defined.
    3. Specify the trace elements that you want to include with XMSDotnetTraceSpecification.
      You can string multiple trace elements together by using a ':' (colon) delimiter.
      • ComponentName is the name of the class that you want to trace. You can use a * wildcard character in this name. For example, *=all=enabled specifies that you want to trace all classes, and IBM.XMS.impl.*=all=enabled specifies that you require API trace only.
      • type can be any of the following trace types: all, debug, event, EntryExit.
      • state can be either enabled or disabled.
    4. Set the trace file size with XMSDotnetTraceFileSize.
      The default maximum is 20 MB, which is specified as XMSDotnetTraceFileSize=20.
    5. Set the number of trace files that are to be retained with XMSDotnetTraceFileNumber.
      The default is 4 (one active file and three archive files). The minimum number allowed is 2.
  • To stop trace, set XMSDotnetTraceLevel to 0.
    This is the default value for this attribute.