When working on On Demand Consulting IIB tickets we will ask the customer for an IIB user trace and maybe an IIB service trace if a PMR is opened IBM will most likely ask for a service trace to aid with the problem resolution. Occasionally when we go on a screen sharing session with a customer we may ask for the IIB debugger to be used or the IIB V10 Flow Exerciser feature.

Our IIB configuration and example message flow

For the purposes of this article we have an IIB V10 node name IB10NODE associated with a queue manager IB10QMGR the IIB Node and IIB Toolkit are both V10.0.0.8. All components are running on the same Windows image we have created an Integration Server named 'default'.

On the default Integration Server we have deployed an application AP_PJB_SOAP which contains a message flow MF_PJB_SOAP a library LB_PJB_SOAP which contains some WSDL definitions. . Also deployed to the

We also have a simple message flow - MF_SOAP_PJB- that takes an incoming XML message from an MQ Queue forwards it onto a web service and then replies to another MQ Queue it would look something like this:


MF_PJB_SOAP is in application AP_PJB_SOAP which references library LB_PJB_SOAP both the application and library are deployed to 'default' Integration Server.

Tracing the message flow

1. The commands to be used - assuming the IIB Node is named 'IB10NODE' the Integration Server is named 'default' and we are gathering a user trace - are:Start the trace: mqsichangetrace IB10NODE -u -e default -l debug -r
2. Run the test
3. Stop the trace: mqsichangetrace IB10NODE -u -e default -l none
4. Read the trace log: mqsireadlog IB10NODE -e default -u -f -o c:\PJB\Temp\trace.xml
5. Format the trace: mqsiformatlog-i c:\PJB\Temp\trace.xml -o c:\PJB\Temp\trace.txt

• -u denotes a user trace -t would be used for a service trace
• -l debug denotes the level of trace is set at the highest level - debug a value of 'none' is used to turn trace off the other possible value is 'normal' which results in a less detailed output than 'debug'.
• -r in the mqsichangetrace command resets (clears) the trace log before starting the trace
• -f in the mqsireadlog -i and -o in the mqsiformat logcommands dictates where the output xml file will be written and read from and where the final - human readable - text file is output to.

More information on these commands can be found in the IIB Knowledge Centre at the following locations:

mqsichangetrace:
mqsireadlog:
mqsiformatlog:

User Trace

User trace is normally used by IIB Developers to aid debugging message flow the result of each node and ESQL/Java statement is logged to the trace.

Service Trace

Service trace is - as the name suggests - normally used by IBM service teams to analyse problems. Service trace produces very detailed output the format of which is not publicly available. You will often be asked to produce a service trace as part of the PMR process. The IIB Knowledge Centre has this to say about service trace:

"..Activate service trace only when you receive an error message that instructs you to or when directed to do so by your IBM Support Center.."

This information can be found here:

https://www.ibm.com/support/knowledgecenter/SSMKHH_10.0.0/com.ibm.etools.mft.doc/an01320_.htm

Tracing specified IIB Applications or message flows

It is quite probable that an IIB Integration Server will have a large number of Application Libraries and Message Flows deployed to it tracing such a Integration Server will could result in a large amount of trace output which may not be relevant to the solving the problem. The IIB trace output can be restricted to an individual message flow using the -f -k and -y flags on the mqsichangetrace command for example:
 
Which tells the IIB runtime to trace the message flow MF_PJB_SOAP that resides in the application AP_PJB_SOAP. If we ran the command omitting the -k AP_PJB_SOAP then the command will fail because it would not find MF_PJB_SOAP residing outside of an application or library. Specifying the -f flag without the -k or -y flags is there to allow debugging of message flows that were deployed outside of applications and libraries.

Trace impact on performance

Using trace does have an impact on performance. How large the impact is depends on the number of components being traced - that is the number of message flows - the complexity of those components and the size and frequency of messages being processed. Service trace has a bigger performance impact than user trace because service trace gathers more detailed information.

Trace Nodes

Trace nodes can be inserted into a message flow each node can have one or more custom patterns that determine what data is written out to the trace. The trace node output can be sent to a file the system event log or IIB trace. On Windows the event log is viewed using the Windows Event View on Linux and Unix by default IIB messages and trace node output are sent to /var/log/messages - but the OS administrator can change this. Trace node output directed to the system event log will use the BIP3051 message number. IIB Trace output is accessed using the mqsichangetrace/mqsireadlog/mqsiformatlog commands discussed previously in trace section of this document.

Examples of patterns used in trace node are: ${Root} ${Environment} ${LocalEnvironment} and ${ExceptionList} which trace the whole of the message passing through the trace node the Environment tree the LocalEnvironment and the ExceptionList tree respectively. More granular tracing can be specified for example:

       ${LocalEnvironment.Destination.MQ.DestinationData}

Eye catcher text and date and time stamps can be added to Trace node patterns to aid problem solving for example the pattern:

  ******** ${CURRENT_TIMESTAMP}${Root}======================

Which results in the following trace node output:
******** 2017-06-13 08:25:14.231793
( ['MQROOT' : 0xa830ed0]
 (0x01000000:Name ):Properties = ( ['MQPROPERTYPARSER' : 0x2785a670]
    (0x03000000:NameValue):MessageSet          = '' (CHARACTER)
    (0x03000000:NameValue):MessageType           = '' (CHARACTER)
    (0x03000000:NameValue):MessageFormat           = '' (CHARACTER)
    (0x03000000:NameValue):Encoding                = 273 (INTEGER)
    (0x03000000:NameValue):CodedCharSetId          = 437 (INTEGER)
.
.
.
======================

       mqsichangetrace IB10NODE -n off -e default And to turn the trace nodes on:  

       mqsichangetrace IB10NODE -n on -e default

This avoids the need to remove trace nodes before putting a message flow into production BUT some care must be taken to make sure that trace node are turned off unless needed. Also if traces nodes are to be left in messages flows going into production some standards should be adopted around their use (where they are placed in a message flow) and what data is output via the pattern specification to make sure debugging requirements are met.

Trace nodes should not be used to message flow logging if you need logging in your message flows use the IAM3 Log4J support-pac found here here:

IIB Test Client

IIB V9 and earlier versions of WebSphere Message Broker provide the Test Client which is invoked by right clicking on the message flow in the IIB Toolkit and selecting 'Test...' The Test client provides the ability to save test messages and the results of any tests. The IIB Test Client is documented here:

https://www.ibm.com/support/knowledgecenter/SSMKHH_9.0.0/com.ibm.etools.mft.doc/af52104_.htm

In IIB v10 the Test Client has been removed and the the Flow Exerciser introduced.

IIB V10 Flow Exerciser

The IIB flow exerciser provide the ability to inject messages through message flows and view the path the message take through the flow and the message LocalEnvironment Environment and Exception List tress between nodes. You cannot set breakpoints or change data values during message flow execution using the flow exerciser to do that you need to use the IIB debugger.
The flow exerciser is launched by clicking on the flow exerciser red button in the message flow editor:



Starting the flow exerciser causes the IIB application containing the message flow - and any required libraries to be deployed to the integration server then the following dialog is shown:



When this dialog is dismissed the message flow editor is greyed out and you can't make changes to the message flow until you click on the red 'x' next to the flow exerciser titles to stop the flow exerciser recording messages highlighted in red in this screenshot:



To send a message through the flow click on the icon highlighted in blue in the previous screenshot which will launch the 'send message' dialog:



The first time the send message dialog is started for a message flow it will appear as per the screenshot above with no messages listed in the Input Messages section because no test messages have been created yet. Once we've created a test message it will appear in the Input Messages section each time Send Message is started until it deleted.

To add a new message click on the envelope (New Message) icon highlighted in red above. The icons next to the new message allow us to duplicate a test message or delete a message once created.

Clicking on new message adds a new to the Input Message folder and opens the message editor:



Here you can type in a message manually if you wish or import an existing message from a file. Clicking on 'Import from file' allows selection of a file either from the current workspace or from the file system. In the screenshot below we imported an xml that we had in the workspace:



Note the 'Header' twisty that allows you to alter the MQMD header - because this message flow uses an MQ Input node. Also notice the 'Input Location' drop-down if there was more than one MQ Input node they would be listed in this drop-down we only have one MQ Input node in our example message flow.

The 'Export Source..' button allows you to export the message to the file system. This might be useful if you've created the message manually rather than importing it from an existing file.

Clicking on 'Send' send the message to the message flow via the input node selected in 'Input Location' the 'Progress Information' dialog is displayed which shows the message being input to the flow and the flow exerciser waiting for a response:



Once the reply message has been retrieved from the MQ queue PJB_OUT a status of 'Stopped' is shown Clicking on close takes us back to the message flow with the execution path highlighted in green:



Clicking on the envelope icons between the nodes will display the message tree being passed between the two node and the Environment and LocalEnvironment trees. Clicking on the envelope between the 'SOAP Envelope' and 'SOAP Request' Nodes shows:



Should the message flow execution cause an exception the progress information will show that the message has been sent to the PJB_FAILURE terminal and queue. Examining the Exception List before the PJB_FAILURE node will show the exception that has caused the message to routed to the failure queue.

IIB Debugger

Both IIB and WebSphere Message Broker have provided the debugger for some time. The debugger allows breakpoints on connections between nodes in a message flow and on Java/ESQL statements in compute nodes. You can examine and modify variables on the fly to change processing path.

Using the IIB debugger is normal practice single user development environments for unit testing where the both the IIB Toolkit and IIB runtime node run on the developers desktop machine and the runtime is not shared with anyone else. other developers or testers sending messages to the message flow being debugged in the same integration node and being held up by breakpoints set by another user. One solution to this issue to have separate integration servers for use with the IIB debugger with the debug port number included in the integration server name for example TestServer1-8888 so that debug ports can be easily identified and clashes avoided.

Breakpoints can be added and removed from connections between nodes in a message flow by right-clicking on the connection and selecting 'Add Breakpoint' or 'Remove Breakpoint'. When there are a number of connection to and from a node and breakpoints are required on all of them it is quicker to right click on the node and select either 'Add Breakpoints Before Node' or 'Add Breakpoints After Node' which will add breakpoints to all connections coming into or out of the node there is no equivalent 'Remove Breakpoints Before/After node.

You can also add breakpoints for statements in ESQL or Java compute nodes by right clicking in the left hand margin of the editor and selecting 'Enable Breakpoint' a breakpoint added in this way can be removed.
Once breakpoints have been added the debugger in the toolkit must be attached to a integration server this is done by clicking on the integration server and selecting 'Launch debugger (Port is xxxx)'. If the port number shows '0' then you will need to select a free port number on the machine where the IIB node is running in. More information can be found here:
Once the debugger is attached to the runtime when the message flow processes an incoming message the toolkit which will switch to the message flow debug perspective - assuming that a breakpoint has been set on a path in the message flow that is executed by this message.

Once in the debug perspective the 'Debug' view (in the top left corner by default) you chose to continue to the next breakpoint step into the code in a compute node - if the next node is a compute node or step onto the next connection breakpoint.

At the top right of the Debug perspective are the 'Variables' and 'Breakpoints' views. In the variables view you can expand and view the Message tree as well as the LocalEnvironment Environment and ExceptionList trees if they are present:



You can also change the value of a variable to alter the execution of the message flow if this example we have changed the value of firstName from 'Eric' to 'xxxxx'.

The Breakpoints view shows all the breakpoints currently set for all message flows in the workspace. for example:



Breakpoints can removed or disabled by clicking on the check-box adjacent to the breakpoint name. To remove a single breakpoint select it click on the single 'x' at the top right of the breakpoints view to remove all the breakpoints click on the double 'x' at the top right of the breakpoints view.

You cannot use the IIB debugging to step through the transformations in a mapping nod if you need to debug a mapping node use the user trace a debug level described earlier.

Useful testing tools

Aside from the IIB functionality discussed in this article there a few tools that are regularly used when test IIB message flows these are:

• rfhutil GUI tool that puts and gets messages from MQ queues with full access to the MQMD and RFG2 headers. This part of IBM support pac IH03 which can be found here: http://www-01.ibm.com/support/docview.wss?uid=swg24000637
• SoapUI from SmartBear used to test SOAP web services can be used to set up mock web services that IIB message flows can call from SOAP Request nodes (as per our example) as well is testing web services implemented using IIB SOAP Input and SOAP Reply nodes.11111c1