This topic contains sections marked as revised for this release

WebSphere Message Brokers
File: ac04840_
Writer: Terry Cowling

Reference topic

This build: July 31, 2007 21:17:42

Trace node

The Trace node generates trace records that you can use to monitor the behavior of a message flow.

This topic contains the following sections:

Purpose

Use the Trace node to generate trace records that can incorporate text, message content, and date and time information, to help you to monitor the behavior of the message flow.

You can write the records to the user trace file, another file, or the local error log (which contains error and information messages written by all other WebSphere® Message Broker components). If you write traces to the local error log, you can issue a message from the default message catalog that is supplied with WebSphere Message Broker, or you can create your own message catalog.

The operation of the Trace node is independent of the setting of user tracing for the message flow that contains it. In particular, records that are written by the Trace node to the user trace log are written even if user trace is not currently active for the message flow.

The Trace node is contained in the Construction drawer of the palette, and is represented in the workbench by the following icon:

Trace node icon

Using this node in a message flow

Look at the following samples to see how to use this node:

You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.

Include a Trace node to help diagnose errors in your message flow. By tracing the contents of the message at various points in the flow, you can determine the sequence of processing. You can configure the Trace node to record the content of a message, and to check the action of a specific node on the message. For example, you can include a Trace node immediately after a Compute node to check that the output message has the expected format.

You can also use the Trace node to provide information in error handling within your message flows. For example, you can use this node to record failures in processing due to errors in the content or format of a message.

Remove Trace nodes from your message flow when you have tested the message flow, and have proved that its operation is correct.

Configuring the Trace node

When you have put an instance of the Trace node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

Configure the Trace node as follows:
  1. Optional: On the Description tab, enter a short description, a long description, or both. You can also rename the node on this tab.
  2. On the Basic tab:
    1. Set the property to indicate where to write the output from the Trace node. The Destination refers to the computer that hosts the broker on which the Trace node is deployed:
      • To write the trace record to the local system error log, select Local Error Log.

        The information that you include in the trace record is written to one of the following locations:

        • Windows platform On Windows®, data is written to the Event log (Application View)
        • Linux platform UNIX platform On Linux® and UNIX®, data is written to the syslog
        • z/OS platform On z/OS®, data is written to the operator console

        If you select Local Error Log, indicate the number of the trace message that is to be written, and the message catalog in which the message is defined.

        • If you leave Message Catalog blank, the default message catalog that is supplied with WebSphere Message Broker is used as the source of the message that is to be written.

          You must also enter the error number of the record in Message Number. Numbers 3051 to 3099 are reserved in the WebSphere Message Broker (default) catalog for this use. The text of each of these messages in the default message catalog is identical, but if you use a different number within this range for each situation that you trace, you can identify the exact cause of the error. The default message number is 3051.

        • If you create your own message catalog, enter the fully-qualified file name for your catalog in Message Catalog.

          You must also enter the appropriate number for the message in the catalog that you want to write to the local error log in Message Number. On some systems, message numbers that end 00 are reserved for system use; do not include messages with numbers like 3100 in your message catalog.

      • To write the trace record to the system-generated user trace log, select User Trace.

        These records are written regardless of the setting of the User Trace property for the deployed message flow.

        The user trace is written to the \log subdirectory of the root directory (for example, the default path on Windows is C:\Documents and Settings\All Users\Application Data\IBM\MQSI\common\log). The file name is made up of the broker name, the broker UUID, and a suffix of userTrace.bin (for example, broker.e51906cb-dd00-0000-0080-b10e69a5d551.userTrace.bin.0). Use the mqsireadlog and mqsiformatlog commands before you view the user trace log.

      • To write the trace record to a file of your choice, select File.

        If you select this option, you must also set File Path to the fully-qualified path name for the trace. If you do not set the path, the location of the file depends on the system; for example, on z/OS, the file is created within the home directory of the broker service ID.

        You can use any name for the trace file; for example, c:\user\trace\trace.log

        If you specify a file that does not exist already, the file is created. However, directories are not created by this process, so the full path must already exist.

        The file is written as text, in the format specified by the Pattern property. You do not need to run the mqsireadlog or mqsiformatlog commands against the file.

      • If you do not want to write any trace records, select None.
    2. In Pattern, create an ESQL pattern to specify what information to write. If you write the trace record to the local error log, the pattern governs the information that is written in the text of the message number that is selected. If you use the default message catalog, and a number between 3051 and 3099, the pattern information is inserted as &1 in the message text.
      • You can write plain text, which is copied into the trace record exactly as you have entered it.
      • You can identify parts of the message to write to the trace record, specifying the full field identifiers enclosed within the characters ${ and }. To record the entire message, specify ${Root}.
      • Use the ESQL functions to provide additional information; for example, use the ESQL function CURRENT_DATE to record the date, time, or both, at which the trace record is written.

      The pattern below illustrates some of the options that are available. The pattern writes an initial line of text, records two elements of the current message, and adds a simple timestamp:

      Message passed through with the following fields:
      Store name is ${Body.storedetailselement.storename}
      Total sales are ${Body.totalselement.totalsales}
      Time is: ${EXTRACT(HOUR FROM CURRENT_TIMESTAMP)}
      		:${EXTRACT(MINUTE FROM CURRENT_TIMESTAMP)}

      The resulting trace record is:

      Message passed through with the following fields:
      Store name is 'SRUCorporation'
      Total sales are '34.98'   
      Time is: 11:19

      A pattern that contains syntax errors does not prevent a message flow that contains the Trace node from deploying, but the node writes no trace records.

Terminals and properties

The terminals of the Trace node are described in the following table.

Terminal Description
In The input terminal that accepts a message for processing by the node.
Out The output terminal through which the message is propagated.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).

The Description properties of the Trace node are described in the following table.

Property M C Default Description
Node name No No The node type The name of the node.
Short Description No No   A brief description of the node.
Long Description No No   Text that describes the purpose of the node in the message flow.

The Basic properties of the Trace node are described in the following table.

Property M C Default Description
Destination Yes No User Trace The destination of the trace record that is written by the node. Valid values are User Trace, File, Local Error Log, and None.
File Path No Yes   The fully-qualified file name of the file to which to write records. This property is valid only if Destination is set to File.
Pattern No No   The data that is to be included in the trace record.
Message Catalog No No   The name of the message catalog from which the error text for the error number of the exception is extracted. The default value (blank) indicates that the message is taken from the message catalog that is supplied with WebSphere Message Broker.
Message Number No No 3051 The error number of the message that is written.
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:17:42

ac04840_ This topic's URL is: