mqsichangetrace command

Use the mqsichangetrace command to set the tracing characteristics for an integration node.

Supported platforms

  • Windows
  • Linux® and UNIX systems
  • z/OS® - as a console command

Purpose

This command is valid for:
  • User trace. Specify the -u option.
  • Service trace. Specify the -t option. Use this option only if directed to do so by the action described in a BIPxxxx message, or by your IBM® Support Center.
  • Trace nodes. Specify the -n option to switch Trace nodes on or off. You can significantly improve the performance of a flow by switching Trace nodes off.

You can initiate, modify, or end user (or service) tracing for an integration node.

You can switch Trace nodes for an integration node on and off, but you cannot use this command to initiate service tracing for the IBM Integration Toolkit.

If you specify an integration node, or any of its resources (integration server or message flow), you must have deployed them before you can start trace. If you want to use the mqsichangetrace command to start or stop user trace, you must ensure the integration node is running. But for service trace, you can also use the mqsichangetrace command to enable or disable trace when the integration node is in a shutdown state. This allows you to trace the startup of the integration node components.

The output for service and user trace generated by these commands is written to trace files in the log subdirectory. When you have completed the work you want to trace, use the mqsireadlog command to retrieve the log as an XML format file. Use either the mqsiformatlog command (to produce a formatted file), or an XML browser to view the XML records.

When you set tracing on, you cause additional processing to be executed for every activity in the integration node that you are tracing. Expect performance to be affected when trace is active.

If you want to trace the command processes themselves, set the environment variables MQSI_UTILITY_TRACE and MQSI_UTILITY_TRACESIZE before you initiate trace.

You can set MQSI_UTILITY_TRACE to normal or debug, depending whether you want normal or debug tracing, and you should set MQSI_UTILITY_TRACESIZE to the maximum size of the trace file that you require in kilobytes (KB), the default being 102400 (100MB).

Ensure that you reset these variables when tracing for the selected command is complete. If you do not do so, all subsequent commands are also traced, and their performance degraded. For more information about MQSI_UTILITY_TRACE and MQSI_UTILITY_TRACESIZE, see Starting service trace.

You can also start and stop tracing activity for integration servers and message flows using the facilities of the IBM Integration Toolkit. See User trace for more information.

If you want to view the tracing options that are currently in effect, use the mqsireporttrace command.

To enable service trace of your custom integration applications, take one of the following steps:
  • Call the method BrokerProxy.enableAdministrationAPITracing(String filename).
  • Before running your custom integration application, set the environment variable MQSI_CMP_TRACE to the name of the file to which trace is sent.
Select the appropriate link for details of this command on the platform, or platforms, that your enterprise uses:

Authorization

For information about platform-specific authorizations, see the following topics: If you have enabled integration node administration security, you must also set up the authority that is detailed in Tasks and authorizations for administration security.