Chapter 7. Debugging a routing context

This tutorial shows how to use the Camel debugger to find logic errors for a locally running routing context.

Goals

In this tutorial you complete the following tasks:

  • Set breakpoints on the nodes of interest in the two routes
  • In the Debug perspective, step through the routes and examine the values of message variables
  • Step through the routes again, changing the value of a message variable and observing the effect

Prerequisites

To start this tutorial, you need the ZooOrderApp project resulting from one of the following:

Setting breakpoints

In the Debugger, you can set both conditional and unconditional breakpoints. In this tutorial, you only set unconditional breakpoints. To learn how to set conditional breakpoints (that are triggered when a specific condition is met during the debugging session), see the Tooling User Guide.

To set unconditional breakpoints:

  1. If necessary, open your ZooOrderApp/src/main/resources/OSGI-INF/blueprint/blueprint.xml in the route editor.
  2. In Project Explorer, expand Camel Contextssrc/main/resources/OSGI-INF/blueprint/blueprint.xml to expose both route entries.
  3. Double-click the Route_route1 entry to switch focus to Route_route1 in the Design tab.
  4. On the canvas, select the Choice_choice1 node, and then click its red icon icon to set an unconditional breakpoint:

    BPnodeIcons
    forward nav
    BPnodeIcons2
    Note

    In the route editor, you can disable or delete a specific breakpoint by clicking the node’s gray icon icon or its delete icon icon, respectively. You can delete all set breakpoints by right-clicking the canvas and selecting Delete all breakpoints.

  5. Set unconditional breakpoints on the following Route_Route1 nodes:

    • Log_log1
    • SetHeader_setHeader1
    • To_Invalid
    • Log_log2
    • SetHeader_setHeader2
    • To_Fulfill
  6. In Project Explorer, double-click Route_route2 under src/main/resources/OSGI-INF/blueprint to open Route_route2 on the canvas.
  7. Set unconditional breakpoints on the following Route_Route2 nodes:

    • Choice_choice2
    • SetHeader_setHead_usa
    • Log_usa
    • To_US
    • SetHeader_setHead_ger
    • Log_ger
    • To_GER

Stepping through the routing context

You can step through the routing context in two ways:

  • Step over ( Step Over icon ) - Jumps to the next node of execution in the routing context, regardless of breakpoints.
  • Resume ( Resume icon ) - Jumps to the next active breakpoint in the routing context.

    1. In Project Explorer, expand the ZooOrderApp project’s Camel Contexts folder to expose the blueprint.xml file.
    2. Right-click the blueprint.xml file to open its context menu, and then click Debug AsLocal Camel Context (without tests).

      The Camel debugger suspends execution at the first breakpoint it encounters and asks whether you want to open the Debug perspective now:

      tutCnfrmPerspSwitch
    3. Click Yes.

      Note

      If you click No, the confirmation pane appears several more times. After the third refusal, it disappears, and the Camel debugger resumes execution. To interact with the debugger at this point, you need to open the Debug perspective by clicking WindowOpen Perspective → > Debug.

      The Debug perspective opens with the routing context suspended at _choice1 in _route1 [blueprint.xml] as shown in the Debug view:

      tutDebugPerspOpen1
      Note

      Breakpoints are held for a maximum of five minutes before the debugger automatically resumes, moving on to the next breakpoint or to the end of the routing context, whichever comes next.

    4. In the Variables view, expand the nodes to expose the variables and values available for each node.

      As you step through the routing context, the variables whose values have changed since the last breakpoint are highlighted in yellow. You might need to expand the nodes at each breakpoint to reveal variables that have changed.

    5. Click Resume icon to step to the next breakpoint, _log2 in _route1 [blueprint.xml]:

      tutDBResumeLog2Rte1
    6. Expand the nodes in the Variables view to examine the variables that have changed since the last breakpoint at _choice1 in Route1 [blueprintxt.xml].
    7. Click Resume icon to step to the next breakpoint, _setHeader2 in Route1 [blueprint.xml].

      Examine the variables that changed (highlighted in yellow) since the breakpoint at _log2 in Route1 [blueprint.xml].

    8. In the Debug view, click _log2 in _route1 [blueprint.xml] to populate the Variables view with the variable values from the breakpoint _log2 in _route1 [blueprint.xml] for a quick comparison.

      In the Debug view, you can switch between breakpoints within the same message flow to quickly compare and monitor changing variable values in the Variables view.

      Note

      Message flows can vary in length. For messages that transit the InvalidOrders branch of Route_route1, the message flow is short. For messages that transit the ValidOrders branch of Route_route1, which continues on to Route_route2, the message flow is longer.

    9. Continue stepping through the routing context. When one message completes the routing context and the next message enters it, the new message flow appears in the Debug view, tagged with a new breadcrumb ID:

      tutDBviewNextMsg

      In this case, ID-janemurpheysmbp-home-55846-1471374645179-0-3 identifies the second message flow, corresponding to message2.xml having entered the routing context. Breadcrumb IDs are incremented by 2.

      Note

      Exchange and Message IDs are identical and remain unchanged throughout a message’s passage through the routing context. Their IDs are constructed from the message flow’s breadcrumb ID, and incremented by 1. So, in the case of message2.xml, its ExchangeId and MessageId are ID-janemurpheysmbp-home-55846-1471374645179-0-4.

    10. When message3.xml enters the breakpoint _choice1 in _route_route1 [blueprint.xml], examine the Processor variables. The values displayed are the metrics accumulated for message1.xml and message2.xml, which previously transited the routing context:

      tutMsg3Choice1Stats

      Timing metrics are in milliseconds.

    11. Continue stepping each message through the routing context, examining variables and console output at each processing step. When message6.xml enters the breakpoint To_GER in Route2 [blueprint.xml], the debugger begins shutting down the breadcrumb threads.
    12. In the Menu bar, click Terminate icon to terminate the Camel debugger. The Console terminates, but you must manually clear the output.

      Note

      With a thread or endpoint selected under the Camel Context node in the Debug view, you must click Terminate icon twice - first to terminate the thread or endpoint and second to terminate the Camel Context, thus the session.

    13. In the Menu bar, right-click tutDebugPersp to open the context menu, and then select Close to close Debug perspective.

      Developer Studio automatically returns to the perspective from which you launched the Camel debugger.

    14. In Project Explorer, right-click the project and then select Refresh to refresh the display.

      Note

      If you terminated the session prematurely, before all messages transited the routing context, you might see, under the ZooOrderApp/src/data folder, a message like this: message3.xml.camelLock. You need to remove it before you run the debugger on the project again. To do so, double-click the .camelLock message to open its context menu, and then select Delete. When asked, click OK to confirm deletion.

    15. Expand the ZooOrderApp/target/messages/ directories to check that the messages were delivered to their expected destinations:

      tutDualCBRrteVerify

Leave the routing context as is, with all breakpoints set and enabled.

Changing the value of a variable

In this section, you add variables to a watch list to easily check how their values change as messages pass through the routing context. You change the value of a variable in the body of a message and then observe how the change affects the message’s route through the routing context.

  1. To rerun the Camel debugger on the ZooOrderApp project, right-click the blueprint.xml file and then click Debug AsLocal Camel Context (without tests).
  2. With message1 stopped at the first breakpoint, _choice1 in _route1 [blueprint.xml], add the variables NodeId and RouteId (in the Exchange category) and MessageBody and CamelFileName (in the Message category) to the watch list.

    For each of the four variables:

    1. In the Variables view, expand the appropriate category to expose the target variable:
    2. Right-click the variable (in this case, NodeId in the Exchange category) to open the context menu and select Watch:

      FTVarNodeIDWatch

      The Expressions tab opens, listing the variable you selected to watch:

      FTWatchM1NodeId
      Note

      Creating a watch list makes it easy for you to quickly check the current value of multiple variables of interest.

  3. Step message1 through the routing context until it reaches the fourth breakpoint, _Fulfill in _route1 [blueprint.xml].
  4. In the Variables view, expand the Message category.
  5. Add the variable Destination to the watch list.

    The Expressions view should now contain these variables:

    FTWatchM1R1toFfil
    Note
    • The pane below the list of variables displays the value of the selected variable.
    • The Expressions view retains all variables that you add to the list until you explicitly remove them.
  6. Step message1 through the rest of the routing context and then step message2 all of the way through.
  7. Stop message3 at _choice1 in _route1 [blueprint.xml].
  8. In the Variables view, expand the Message category to expose the MessageBody variable.
  9. Right-click MessageBody to open its context menu, and select Change Value:

    tutVarChngMenuMsg2
  10. Change the value of quantity from 15 to 10 (to change it from an invalid order to a valid order):

    tutChgVarsMsg2

    This changes the in-memory value only (it does not edit the message3.xml file).

  11. Click OK.
  12. Switch to the Expressions view, and select the MessageBody variable.

    The pane below the list of variables displays the entire body of message3, making it easy to check the current value of order items:

    FTWatchM2R1toFfilVarChng
  13. Click Resume icon to step to the next breakpoint.

    Instead of following the branch leading to To_Invalid, message3 now follows the branch leading toTo_Fulfill and Route_route2.

Narrowing the Camel debugger’s focus

You can temporarily narrow and then re-expand the debugger’s focus by disabling and re-enabling breakpoints:

  1. Step message4 through the routing context, checking the Debug view, the Variables view, and the Console output at each step.
  2. Stop message4 at _choice1 in _route1 [blueprint.xml].
  3. Switch to the Breakpoints view, and clear each check box next to the breakpoints listed below _choice1. Clearing the check box of a breakpoint temporarily disables it.

    tutBreakptsDisabled
  4. Click Resume icon to step to the next breakpoint:

    tutMsg3toFulfillRte1

    The debugger skips over the disabled breakpoints and jumps to _FulFill in _route1 [blueprint.xml].

  5. Click Resume icon again to step to the next breakpoint:

    tutMsg3toUKRte2

    The debugger jumps to _GER in _route2 [blueprint.xml].

  6. Click Resume icon repeatedly to quickly step message5 and message6 through the routing context.
  7. Switch to the Breakpoints view, and check the boxes next to all breakpoints to reenable them.

Verifying the effect of changing a message variable value

To stop the debugger and check the results of changing the value of `message1’s quantity variable:

  1. In the tool bar, click Terminate icon to terminate the Camel debugger:

    tutDBTerminateNorm
  2. Click the Console’s Clear output icon button to clear the output.
  3. Close the Debug perspective and return to the perspective from which you launched the Camel debugger.
  4. In Project Explorer, refresh the display.
  5. Expand the ZooOrderApp/target/messages/ directories to check whether the messages were delivered as expected:

    tutPETargetDestsChngedVars

    You should see that only message1 was sent to the invalidOrders and that message3.xml appears in the validOrders/Germany folder.

Next steps

In the Chapter 8, Tracing a message through a route tutorial, you trace messages through your routing context to determine where you can optimize and fine tune your routing context’s performance.