Viewing the logical message tree in trace output

To view the structure of the logical message tree at any point in the message flow, include a Trace node and write some or all the message (including headers and all four message trees) to the trace output destination.

About this task

You might find trace output useful to check or record the content of a message before and after a node changes it, or on its receipt by the input node. For example, if you include a Compute node that builds a destination list in the local environment tree, you might want a record of the structure that it created as part of an audit trail. Also, you might want to check that the Compute node is working as you expect it to.

UNIX platformOn UNIX, syslog entries are restricted in length and messages that are sent to the syslog are truncated by the newline character. To record a large amount of data in a log on UNIX, set the Destination property on the Trace node to File or User Trace instead of Local Error Log.

Procedure

  1. Switch to the Integration Development perspective.
  2. Open the message flow for which you want to view messages.
    Open an existing message flow, or create a message flow.
  3. Include a Trace node wherever you want to view part or all the message tree structure.
    You can include as many Trace nodes as you choose; however, each node that you introduce can affect the performance of message flow processing.
  4. Set the Trace node properties to trace the message, or parts of the message, that you want to view.
    Specify the parts of the message by using ESQL field references. Several examples are included later in this topic.
  5. If you added a Trace node to investigate a particular behavior of your message flow, and resolved your concerns or checked that the message flow is working correctly, remove the Trace node or nodes, and redeploy the message flow.

Example

Assume that you configured a message flow that receives an XML message on an IBM® MQ queue in an MQInput node. The input message includes an MQRFH2 header. The message has the following content:

<Trade type='buy'
 Company='IBM'
 Price='200.20'
 Date='2000-01-01'
 Quantity='1000'/>

You can include and configure a Trace node to produce output that shows one or more of the trees that are created from this message: the message body, environment, local environment, and exception trees. If you choose to record the content of the message body, the Properties tree and the contents of all headers (in this example, at least an MQMD and an MQRFH2) are included. You specify what you want to be recorded when you set the Trace node property Pattern. You can use most of the correlation names to define this pattern (you cannot use those names that are specific to the Compute node).

Message body
If you want the Trace node to write the message body tree and include Properties and all headers, set Pattern to ${Root}. If you want only the message data, set Pattern to ${Body}.

The trace output that is generated for the message tree of the preceding message with Pattern set to ${Root} would look like the following example:

Root
      Properties
         CreationTime=GMTTIMESTAMP '1999-11-24 13:10:00'          (a GMT timestamp field)
 
  ... and other fields ...
 
      MQMD
         PutDate=DATE '19991124'                                  (a date field)
 
         PutTime=GMTTIME '131000'                                 (a GMTTIME field)
 
  ... and other fields ...
 
      MQRFH
          mcd
          msd='xml'                                              (a character string field)
 
         .. and other fields ...
 
      XML
         Trade
          type='buy'                                             (a character string field)
 
         Company='IBM'                                           (a character string field)
 
         Price='200'                                             (a character string field)
 
         Date='2000-01-01'                                       (a character string field)
 
         Quantity='1000'                                         (a character string field)
Environment
To trace any data in the environment tree, set Pattern to ${Environment}. This setting produces output like the following example: 

( ['MQROOT' : 0x1705f0f4b70]
  (0x01000000:Name):Variables = (
    (0x03000000:NameValue):myVar = 'environment_var_test_data' (CHARACTER)
  )
)

To trace particular variables in the variables folder of the environment tree, you can use a more specific pattern, for example ${Environment.Variables.myVar}. This setting returns the value only (for example, it returns just the value environment_var_test_data).

LocalEnvironment
To trace data in the local environment tree, set Pattern to ${LocalEnvironment}. The output that you get is like the following example, which includes a WrittenDestination folder. This example represents a trace that was written by a Trace node that is included after an MQOutput node, where the Out terminal of the MQOutput node is connected to a sequence of nodes that includes the Trace node. When an Out terminal is connected, the local environment is augmented with information about the action that the output node performed.

( ['MQROOT' : 0x7f83282b0640]
  (0x01000000:Name):Destination        = (
    (0x01000000:Name):MQ = (
      (0x01000000:Name):DestinationData = (
        (0x03000000:NameValue):queueName = 'MQOUT' (CHARACTER)
      )
    )
  )
  (0x01000000:Name):WrittenDestination = (
    (0x01000000:Name):MQ = (
      (0x01000000:Name):DestinationData = (
        (0x03000000:NameValue):queueManagerName        = 'MQSI_SAMPLE_QM' (CHARACTER)
        (0x03000000:NameValue):queueName               = 'MQOUT' (CHARACTER)
        (0x03000000:NameValue):msgId                   = X'414d5120763132716d20202020202020ba993362013b0140' (BLOB)
        (0x03000000:NameValue):replyIdentifier         = X'414d5120763132716d20202020202020ba993362013b0140' (BLOB)
        (0x03000000:NameValue):correlId                = X'000000000000000000000000000000000000000000000000' (BLOB)
        (0x03000000:NameValue):GroupId                 = X'000000000000000000000000000000000000000000000000' (BLOB)
        (0x03000000:NameValue):putDate                 = '20220425' (CHARACTER)
        (0x03000000:NameValue):putTime                 = '17275668' (CHARACTER)
        (0x03000000:NameValue):bindingType             = 'CLIENT' (CHARACTER)
        (0x03000000:NameValue):destinationQueueManager = 'v12qm' (CHARACTER)
        (0x03000000:NameValue):queueManagerHostname    = 'MYQUEUEMANAGERHOSTNAME' (CHARACTER)
        (0x03000000:NameValue):listenerPortNumber      = 9000 (INTEGER)
        (0x03000000:NameValue):channelName             = 'SYSTEM.DEF.SVRCONN' (CHARACTER)
      )
    )
  )
)
ExceptionList
To trace data in the exception list, set Pattern to ${ExceptionList}.

You can also view message structure in the message flow, and other information, when you use the flow debugger.