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 of the message (including headers and all five 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 platform On 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

Switch to the Integration Development perspective.
Open the message flow for which you want to view messages.
Open an existing message flow, or create a message flow.
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.
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.
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, context, 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)
      )
    )
  )
)

Context

To trace the data in the context tree, set Pattern to ${Context}. When context trees are used in a message flow, this shows the content of the context tree for the current flow or subflow.

The context tree for a message flow contains the following types of information:

Flow details

The flow details include the following information about the message flow:

Flow name
Application name
Library name
Integration server name
Integration node name
Hostname (fully qualified hostname)
Process ID

This information does not change between message invocations.

Invocation details

The invocation details contain information about the current message invocation:

Timestamp
Thread ID
Node name (the name of the input or response node that received the invocation)

Nodes

This section contains information about each node that has been propagated through the flow at the point where the tree is viewed.

When using the pattern ${Context} in a subflow, the context tree is shown for that subflow only.

If context trees are not used in a message flow, the pattern ${Context} shows the following output:


 (0x01000000:Name):ContextTree = (
    (0x03000000:NameValue):Enabled = FALSE (BOOLEAN)
  )

It is also possible to use the CONTEXTREFERENCE and CONTEXTINVOCATIONNODE functions within a trace node to display a specific context tree node section in the trace node output. The CONTEXTREFERENCE function can show the context tree section for a specific node in either the current flow/subflow or the propagation path before the subflow. You can specify this by using the following pattern::

${CONTEXTREFERENCE('node label')}

For the CONTEXTREFERENCE function only the comma-separated form of the function can be used in the trace node.

If either of these functions are used when Context trees are not enabled on the message flow then "NULL" is displayed.

Similarly, if the CONTEXTREFERENCE function names a node label that does not exist in the Context tree then "NULL" is displayed."

For more information about context trees, see Context tree.

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.