Chapter 7. To Trace a Message Through a Route

This tutorial shows you how to trace a message through a route.

Goals

In this tutorial you will:

  • Run the CBRroute in the Fuse Integration perspective
  • Enable tracing on the CBRroute
  • Drop messages onto the CBRroute and track them through all route nodes

Prerequisites

To complete this tutorial you will need the CBRroute project you updated in Chapter 5, To Add Another Route to the CBR Routing Context.

Note

If you skipped any tutorial after Chapter 2, To Create a New Route, you can use the prefabricated blueprint6.xml file to work through this tutorial (for details, see Chapter 1, Using the Fuse Tooling Resource Files).

Accessing Fuse Integration perspective

If you are not already working in Fuse Integration perspective:

  1. Click the Open Perspective icon button on the right side of the tool bar, and then select Fuse Integration from the list:

    tutPerspListFIPselected

    Fuse Integration perspective opens in the default layout:

    TutFIP 63
  2. Drag the JMX Navigator tab to the far right of the Terminal tab and drop it there:

    ftTutFIPrearrange

    This arrangement provides more space for Diagram View to display the routing context’s nodes graphically, which makes it easier for you to visually trace the path that messages take in traversing the routing context.

    Note

    To make it easy to access a routing context .xml file, especially when a project consists of multiple contexts, the tooling lists them under the Camel Contexts folder in Project Explorer.

    Additionally, all routes in a routing context are displayed as icons directly under their context file entry. To display a single route in the routing context on the canvas, double-click its icon in Project Explorer. To display all routes in the routing context, double-click the context file entry.

    TutCamelContextsFolderPE

Starting message tracing

To start message tracing on the CBRroute project:

  1. In Project Explorer, expand the CBRroute project to expose src/main/resources/OSGI-INF/blueprint/blueprint.xml.
  2. Right-click src/main/resources/OSGI-INF/blueprint/blueprint.xml to open the context menu.
  3. Select menu:Run As[ > > Local Camel Context (without tests) > ].

    Note

    If you select Local Camel Context, the tooling reverts to running without tests because you have not yet created a JUnit test for the CBRroute project. You will do that later in Chapter 8, To Test a Route with JUnit.

  4. In JMX Navigator, expand Local Processes.

    When you first expand Local Processes, you see the node maven[Id][Disconnected]:

    tutMsgTrJMXLocalProcessess

    When you click this node, it changes to Local Camel Context[Id][Disconnected] (retaining the same Id as its predecessor):

    tutMsgTrJMXLocalCamCntxt
  5. Double click Local Camel Context[Id][Disconnected] to connect to it, and then expand the elements of your route:

    tutMsgTrJMXLCCexpanded
  6. Right-click the _context1 node to open the context menu, and select Start Tracing:

    tutTraceStart

    The tooling displays a graphical representation of your routing context in Diagram View:

    tutDiagramNodes

Dropping messages on the running CBRroute project

To drop messages on the running CBRroute project:

  1. In Project Explorer, expand CBRroute/src/data, so you can access the message files (message1.xml through message6.xml):

    tutMsgFiles
  2. Drag message1.xml and drop it on the _context1>Endpoints>file>src/data?noop=true node in JMX Navigator:

    tutJMXLocalCntxtExpanded

    As the message traverses the route, the tooling traces and records its passage at each step. To update Diagram View with the new message count, you need to click the _context1 node in JMX Navigator.

    Note

    The Local Camel Context[xxx] tree collapses to the _context1 node after you drop the next message on the input src/data?noop=true node. You need not re-expand it. When dragging the other messages, hover over each node in the tree to expose the next node, until you reach the src/data?noop=true node. Then drop the message on it. This method prevents the tooling from redrawing the graphical representation in Diagram View.

Initializing and configuring Messages View

You need to initialize Messages View before it will display message traces. You also need to configure the columns in Messages View if you want them to persist across all message traces.

  1. Switch from Console to Messages View.
  2. Click the _context1 node in JMX Navigator to initialize Messages View with message1.xml's details.

    Note

    You can control columnar layout in all of the tooling’s tables. Use the drag method to temporarily rearrange tabular format. For example, drag a column’s border rule to expand or contract its width. To hide a column, totally contract its borders. Drag the column header to relocate a column within the table. For your arrangement to persist, you must use the menu:View Menu[ > > Configure Columns…​ > ] method instead.

  3. In Messages View, click the View Menu icon icon on the panel’s menu bar, and select Configure Columns…​ to open the Configure Columns wizard:

    TutConfigColsDefaults
    Note

    Notice that the message header, Destination, which you set for the messages in your routing context, appears in the list.

    You can include or exclude items from Messages View by selecting or deselecting them. You can rearrange the columnar order in which items appear in Messages View by highlighting individual, selected items and moving them up or down in the list.

  4. In the Configure Columns wizard, select and order the columns this way:

    tutMsgVCnfgColsMnu

    These columns and their order will persist in Messages View until you change them again.

Arranging Diagram View

To see all message flow paths clearly, you’ll probably need to rearrange the nodes by dragging them to fit neatly in Diagram View. You may also need to adjust the size of the other views and tabs in Red Hat JBoss Developer Studio to allow Diagram View to expand.

Stepping through message traces

To step through the message traces:

  1. In Messages View, click the refresh (Refresh button) on top, right of the panel’s menu bar to populate the view with message1.xml's message traces.

    Each time you drop a message on the input src node in JMX Navigator, you need to refresh Messages View to populate it with the message traces.

  2. Click one of the message traces to see more details about it in Properties view:

    tutTraceDetails2

    The tooling displays the details about a message trace (including message headers when they are set) in the top half of the Properties view and the contents of the message instance in the bottom half of the Properties view. So, if your application sets headers at any step within a route, you can check the Message Details to see whether they were set as expected.

    You can step through the message instances by highlighting each one to see how a particular message traversed the route and whether it was processed as expected at each step in the route.

    In Diagram View, the associated step in the route is highlighted:

    TutMsgTraceDiagNode

Finishing up

  1. Drag message2.xml and drop it on the_context1>Endpoints>file>src/data?noop=true node in JMX Navigator.

    Hover over each node in the tree until you expose the src/data?noop=true node, then drop message2.xml on it.

  2. Switch from Console to Messages View.
  3. In Messages View, click the refresh (Refresh button) on top, right of the panel’s menu bar to populate the view with message2.xml's message traces.

    Note

    You can repeat [msg1drag] through [msgView] for the remaining messages in CBRroute/src/data/ at any time, as long as tracing remains enabled.

    On each subsequent drop, remember to click the refresh (Refresh button) on the panel’s menu bar to populate Messages View with the new message traces.

    The tooling draws the route in Diagram View, tagging paths exiting a processing step with timing and performance metrics (in milliseconds). Only the metric Total exchanges is displayed in the diagram:

    tutTraceFIP 63

    Hovering over the displayed metrics reveals additional metrics about message flow:

    tutDVnodeMetrics
    • Mean time the step took to process a message
    • Maximum time the step took to process a message
    • Minimum time the step took to process a message
  4. When done:

    • In JMX Navigator, right-click _context1 and select Stop Tracing Context from the context menu.
    • Open the Console and click the Stop icon button in the upper right of the panel to stop the Console. Then click the Clear icon button to clear console output.

Next steps

After you create a JUnit test case for your project, you can run your project as a Local Camel Context, instead of Local Camel Context (without tests). See Chapter 8, To Test a Route with JUnit for details.