Configure trace for XMS .NET applications

If we are using IBM MQ classes for XMS .NET Framework, we can configure trace from an application configuration file as well as from the XMS environment variables. If we are using IBM MQ classes for XMS .NET Standard, we must configure trace from the XMS environment variables. We can select the components that we want to trace. Trace is normally used under the guidance of IBM Support.

About this task

Tracing for XMS .NET is based on the standard .NET trace infrastructure.

All tracing except for error tracing is disabled by default.

If we are using IBM MQ classes for XMS .NET Framework, we can turn on tracing and configure the trace settings in either of the following ways:

• By using an application configuration file with a name that consists of the name of the executable program to which the file relates, with the suffix .config. For example, the application configuration file for text.exe would have the name text.exe.config. Using an application configuration file is the preferred way of enabling trace for XMS .NET applications. For further details, see Configure XMS .NET trace using an application configuration file.
• By using XMS environment variables as for XMS C or C++ applications. For further details, see Configure XMS .NET trace using XMS environment variables.

If we are using IBM MQ classes for XMS .NET Standard, we must configure trace from the XMS environment variables. For further details, see Configure XMS .NET trace using XMS environment variables. Using the application configuration file is not supported for IBM MQ classes for XMS .NET Standard.

The active trace file has a name of the format xms_tracePID.log where PID represents the process ID of the application. The size of the active trace file is by default limited to 20 MB. When this limit is reached, the file is renamed and archived. Archived files have names of the format xms_tracePID_YY.MM.DD_HH.MM.SS.log.

By default, the number of trace files that are retained is four, that is, one active file and three archived files. These four files are used as a rolling buffer until the application stops, with the oldest file being removed and replaced by the newest file. We can change the number of trace files by specifying a different number in the application configuration file. However, there must be at least two files (one active file and one archived file).

Two trace file formats are available:

• Basic format trace files are human readable, in a WebSphere Application Server format. This format is the default trace file format. The basic format is not compatible with trace analyzer tools.
• Advanced format trace files are compatible with trace analyzer tools. We must specify that you want to produce trace files in advanced format in the application configuration file.

Trace entries contain the following information:

• The date and time that the trace was logged
• The class name
• The trace type
• The trace message

The following example shows an extract from some trace:

[09/11/2005 14:33:46:914276]	00000004	IBM.XMS.Comms.IoRequest	>	Allocate	Entry
[09/11/2005 14:33:46:914276]	00000004	IBM.XMS.Comms.IoRequest	>	Initialize	Entry
[09/11/2005 14:33:46:914276]	00000004	IBM.XMS.Comms.IoRequest	<	Initialize	Exit
[09/11/2005 14:33:46:914276]	00000004	IBM.XMS.Comms.IoRequest	<	Allocate	Exit

In the previous example, the format is:

[Date Time:Microsecs] 		Thread-id	Classname		Trace-type	Methodname	Entry or Exit

where Trace-type is:

• > for Entry
• < for Exit
• d for Debug information

• Configure XMS .NET trace using an application configuration file
  If we are using IBM MQ classes for XMS .NET Framework, we can configure trace for XMS .NET applications with an application configuration file. The trace section of this file includes parameters that define what is to be traced, the trace file location and maximum allowed size, the number of trace files used, and the trace file format.
• Configure XMS .NET trace using XMS environment variables
  We can turn on trace using XMS environment variables such as XMS_TRACE_ON.

Parent topic: Use trace

Related information

• Use XMS with Microsoft .NET Core
• Downloading IBM MQ classes for XMS .NET Standard from the NuGet repository