Tracing IBM MQ classes for .NET Framework clients using an application configuration file

If you are using IBM® MQ classes for .NET Framework, you can generate trace for the IBM MQ .NET redistributable managed client and stand-alone IBM MQ .NET client by using an application configuration file.

• To start and stop trace, use the application configuration file and an IBM MQ specific trace configuration file.

  Application configuration file (app.config or web.config)

  Applications need to define the MQTRACECONFIGFILEPATH property under the <appSettings> section of the application configuration file, that is, the app.config or web.config file. (The actual name of the application configuration file depends on the name of your application.) The value of the MQTRACECONFIGFILEPATH property specifies the path for the location of the IBM MQ specific trace configuration file, mqtrace.config, as shown in the following example:

  <appSettings>
  <add key="MQTRACECONFIGFILEPATH" value="C:\MQTRACECONFIG" />
  </appSettings>
  

  Tracing is disabled if the mqtrace.config file is not found in the path that is specified application configuration file. However, First Failure Support Technology (FFST) and error logs are created in the application's directory, if the application has authority to write to the current directory.

  IBM MQ specific trace configuration file (mqtrace.config)

  The mqtrace.config file is an XML file that defines properties for starting and stopping trace, the path to the trace files, and the path to the error logs. The following table describes these properties.

  Table 1. Properties defined in the mqtrace.config file

  Attribute	Description
  MQTRACELEVEL	0: Stops tracing - this is the default value. 1: Starts tracing with lesser details. 2: Starts tracing with full details - recommended.
  MQTRACEPATH	Points to a folder where the trace files will be created. The current directory of the application is used if the path is blank or the MQTRACEPATH attribute is not defined.
  MQERRORPATH	Points to a folder where error log files will be created. The current directory of the application is used if the path is blank or the MQERRORPATH attribute is not defined.

  The following example shows a sample mqtrace.config file:

  <?xml version="1.0" encoding="utf-8"?>
  <traceSettings>
    <MQTRACELEVEL>2</MQTRACELEVEL>
    <MQTRACEPATH>C:\MQTRACEPATH</MQTRACEPATH>
    <MQERRORPATH>C:\MQERRORLOGPATH</MQERRORPATH>
  </traceSettings>
  

  Tracing can be started and stopped dynamically when an application is running by altering the value of the MQTRACELEVEL attribute in the mqtrace.config file.

  The running application must have create and write permissions for the folder specified by the MQTRACELEVEL attribute for generating trace files. Applications that are running in an Microsoft Azure PaaS environment must also ensure similar access permissions since web applications that use an IBM MQ .NET assembly running in Microsoft Azure PaaS might not have create and write permissions. The generation of the trace, first failure data capture (FDC), and error logs fails if the application does not have the required create and write permissions for the specified folder.

• To capture tracing events and messages relating to the SSLStream class, add a configuration section for system diagnostics to the application configuration file for your application.
  For more information, see Configuring trace for SSLStream.