Estimated time
00:30
What this exercise is about
This exercise has you use the various tracing and debugging tools to identify problems in message flows, enable and disable trace nodes, and use a user and service trace to capture information.
What you should be able to do
At the end of the exercise, you should be able to:
• Enable and disable a trace node within a message flow • Activate a user trace and service trace to capture information • Administer trace nodes and the message flow debugger
Introduction
You will use various problem determination tools to administer message flows with trace nodes and use administration tools to generate and control tracing.
This exercise uses a flow like the message used in Exercise 2 but with the addition of a trace node.
Required materials
A fully configured workstation, as used in previous exercises.
EX5_PD.bar
The broker archive file for the message flow, located in the C:\Labs\Lab5\resources folder.
EXempty
Exercise instructions
Part 1: Import the BAR file into WebSphere Message Broker Explorer In this part of the exercise, you import an existing BAR file that contains a message flow that is identical to the message flow you used in Exercise 2 except that it has a Trace node.
After you import the BAR file, you will examine the Trace node properties and then deploy the BAR file to the DEVBROKER.
__ 1. In the WebSphere Message Broker Explorer, right-click the Broker Archive Files/Servers folder in the Navigator and select Import Broker Archive Files.
__ 2. Click Browse for the From directory and go to the C:\Labs\Lab5\resources directory and then click OK.
__ 3. In the right pane select the BAR file EX5_PD.bar and then click Finish.
The BAR file should appear in the WebSphere Message Broker Explorer Navigator under the Broker Archive Files/Servers folder.
__ 4. Open the message flow and examine the Trace node properties.
__ a. Double-click the EX5_PD.bar file in the WebSphere Message Broker Explorer Navigator to open the Broker Archive Editor.
__ b. Expand the SimpleFlowWithTrace.cmf file until all the nodes are displayed.
__ c. Select the Trace node labeled Trace to display its properties in the Properties view.
The developer specified that the Trace node should create a trace file. Based on this setting at design time, the only property that can be changed by the
administrator in WebSphere Message Broker Explorer is the location of the trace file. In this exercise, trace file location (filePath) is set to
C:\Labs\Lab5\SimpleFlowtrace.txt.
__ 5. In WebSphere Message Broker Explorer, verify that you have an execution group named default on DEVBROKER; if not create it now.
__ 6. Deploy the EX5_PD.bar to the default execution group in broker DEVBROKER.
__ a. Select the EX5_PD.bar file in the Navigator.
__ b. Drag it onto the default execution group under DEVBROKER in the Brokers folder.
__ c. Check the Administration Log view to verify that the message flow has been deployed successfully.
You should also see the message flow under DEVBROKER in the Brokers folder under the default execution group.
Part 2: Send a test message to the message flow __ 1. Start RfhUtil by double-clicking the desktop shortcut icon.
__ 2. Enter the following parameters on the Main tab in RfhUtil:
• Queue Manager Name: use the drop-down list to select DEVQMGR.
• Queue Name: use the drop-down list to select EX2_IN.
__ 3. Click Open File. A file selection window is displayed.
__ 4. Go to C:\Labs\Lab5\data and select file Test_V2_msg.xml. Click Open.
__ 5. Select the MQMD tab.
__ 6. Update the following fields as noted:
__ a. Use the drop-down list to set the MQ Message Format field to MQSTR (signifying the message is string data) on the drop-down menu
__ b. Use the drop-down list to set the MsgType field to 1 Request (signifying the message is a WebSphere MQ request message).
EXempty • Set the Reply To Queue name to EX2_REPLY so that the MQReply node routes the message to that queue.
__ 7. Switch back to the Main tab, and click Write Q to send the test message to the EX2_IN queue.
__ 8. Open another RfhUtil instance and check the Reply To Queue EX2_REPLY.
__ a. Enter the following parameters on the Main tab in RfhUtil:
• Queue Manager Name: use the drop-down list to select DEVQMGR.
• Queue Name: use the drop-down list to select EX2_REPLY.
__ b. Click Read Q.
__ c. Switch to the Data tab and click XML as the Data Format.
__ d. When viewed as XML the message should appear as follows:
<OutMsg>
<Version>2</Version>
<TimeIs>current time stamp</TimeIs>
<DateIs>current date stamp</DateIs>
</OutMsg>
__ 9. Do not close the RfhUtil session, as you use it later in this lab.
Part 3: User trace and trace node output
__ 1. In WebSphere Message Broker Explorer, activate UserTrace (Debug) for the SimpleFlowWithTrace.msgflow running in the default execution group.
__ a. In the Navigator view, expand the broker DEVBROKER and the default execution group.
__ b. Right-click the SimpleFlowWithTrace message flow and select UserTrace >
Debug.
__ c. Verify that tracing is active in the Administration Log view. You might have to wait briefly, but you will see a message that indicates the user TraceLevel has changed from ‘none’ to ‘debugTrace’.
__ 2. When you select the execution group, the execution group Properties QuickView also indicates that tracing is enabled and has a performance affect.
EXempty __ 3. Send another test message by clicking Write Q in RfhUtil.
Did a message arrive on the EX2_REPLY on queue manager DEVBROKER?
__ 4. Retrieve the user trace data and deactivate tracing by running the GETTRACE script.
Open a WebSphere Message Broker command console window and run this command:
C:\Labs\Tools\GETTRACE.cmd <brokername> <execution group name>
where <brokername> is the name of your broker (in this case, DEVBROKER) and
<execution group name> is the name of the execution group (in this case, default). Remember that the parameters are case-sensitive.
This command file runs several WebSphere Message Broker commands:
- mqsireadlog, which reads the binary trace data that was gathered by the trace node
- mqsiformatlog, which translates the binary trace data into human-readable format
- mqsichangetrace, which disables tracing (and can also be used from the command line to start tracing or change trace parameters)
The command file then starts Windows Notepad to display the trace output.
__ 5. Review the user trace output. You should find all the runtime events (or errors) in the trace.
__ 6. In WebSphere Message Broker Explorer, refresh the message flow to verify that user trace has terminated. If it has not stopped automatically, you can manually disable it.
__ a. In the Navigator view, right-click the message flow and select Refresh.
The message flow Properties QuickView shows the current state of User Trace.
__ b. To manually turn off trace, right-click the message flow and select User Trace >
None.
__ 7. Now review the output from the trace node from the file you indicated in the trace node properties, for example, C:\Labs\Lab5\SimpleFlowTrace.txt
__ a. Use Windows Explorer to locate the trace node output file.
__ b. Open the file and examine the contents. You see the contents of the entire message at the end of the file if you specified ${Root} for the pattern.
Part 4: Enable a service trace
Service trace provides more detailed tracing, and generates a large amount of output. In this exercise, you are given the option of using a command line or WebSphere Message Broker Explorer to enable and disable a service trace.
Option 1: Enable a service trace from a command line
__ 1. In the WebSphere Message Broker command console, issue the following
command to start a service trace for the default execution group. The -r flag resets
EXempty __ 2. Now, to see what tracing is active, issue the following command:
mqsireporttrace DEVBROKER -t -e default You should see a response like the following:
__ 3. Switch to the RfhUtil session and send another message to the EX2_IN queue by clicking Write Q.
__ 4. Disable the service trace by switching to the command console session and entering the following command:
mqsichangetrace DEVBROKER -t -e default -l none
Option 2: Enable a service trace from WebSphere Message Broker Explorer
__ 1. In WebSphere Message Broker Explorer, right-click the default execution group for the DEVBROKER and then select Service trace > Debug.
A warning message is displayed in the Execution Group properties view indicating that there is a performance affect and the Service Trace property is set to Debug.
__ 2. Switch to the RfhUtil session and send another message to the EX2_IN queue by clicking Write Q.
__ 3. Disable the service trace, by right-clicking the default execution group and selecting Service Trace > None.
Part 5: Process the service trace output
Regardless of the method you used to activate a service trace, you must retrieve the service trace data into a file. For this exercise, a command file getsvctrace.cmd performs this function for you. The command file is like the gettrace.cmd that you used when retrieving the user trace data.
__ 1. Retrieve the service trace data from a WebSphere Message Broker command console session by running the following command:
C:\Labs\Tools\getsvctrace.cmd DEVBROKER default
__ 2. Review the service trace output in the Notepad session that is automatically opened by the getsvctrace.cmd.
The information captured in the service trace is more detailed and includes a great deal about the various component behaviors.
Part 6: Administering Trace nodes
As mentioned earlier in this exercise, Trace nodes generate trace records that you can use to monitor the behavior of a message flow. When a developer has tested the message flow and proved that its operation is correct, the Trace nodes should either be removed from the message flow or disabled.
__ 1. Check the status of the Trace nodes in the WebSphere Message Broker Explorer by selecting the SimpleFlowWithTrace message flow under the default execution group in the Navigator view.
The message flow Properties QuickView indicates the current state of the Trace nodes.
__ 2. If the Trace nodes are Enabled, disable them by right-clicking the message flow in the WebSphere Message Broker Explorer Navigator view and selecting Trace Nodes > Disable.
Part 7: Administering the message flow debugger
Developers can use the message flow debugger in the WebSphere Message Broker Toolkit to help diagnose unexpected behavior within message flows. Breakpoints can be set to
EXempty The debug port can be configured in the development environment using WebSphere Message Broker Toolkit or in the administration environment using WebSphere Message Broker Explorer. As an administrator, you also must be aware of the status of the debugger as it does affect performance. Since this is an administration course, you configure and manage the message flow debugger from WebSphere Message Broker Explorer.
Note
JVM debug port configuration must be completed one time for each execution group. The Execution Group Properties QuickView in WebSphere Message Broker Explorer identifies whether a debug port has been configured for an execution group.
__ 1. Check whether a debug port has been defined on the default execution group on DEVBROKER by right-clicking the execution group in the WebSphere Message Broker Explorer Navigator and selecting Flow Debug Port.
The Enable menu option is either followed by a flow debug port value, if one has already been configured, or the phrase (No port set) if not debug port has been defined.
The default execution group should not have a debug port set.
__ 2. To set the debug port, right-click the default execution group under the DEVBROKER and select Properties.
__ 3. Select Extended.
__ 4. Enter a value for the Flow Debug Port. For this exercise, enter 9997 and then click OK.
__ 5. Check the Administration Log to see if the execution group automatically restarted.
__ 6. The Execution Group Properties QuickView is updated to show that a debug port has been set but that it is disabled.
Note
You can also use the mqsichangeproperties command line to configure the JVM debug port:
mqsichangeproperties <brokerName> -e <executionGroup>
-o ComIbmJVMManager -n jvmDebugPort -v <portNumber>
EXempty QuickView indicating that the flow debug port is active and that it affects performance.
__ 8. Disable the message flow debug port by right-clicking the execution group in the WebSphere Message Broker Explorer Navigator and selecting Flow Debug Port >
Disable.
END OF EXERCISE