Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 7. To Trace a Message Through a Route

Abstract

This tutorial walks you through the process of tracing 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 camelContext6.xml file to work through this tutorial (for details, see Chapter 1, Using the Fuse Tooling Resource Files).

Accessing Fuse Integration perspective

To open Fuse Integration perspective and optimally arrange its layout:
  1. Select Window → Open Perspective → Other... → Fuse Integration to open the Fuse Integration perspective, as shown in Figure 7.1.
    Note
    You can use the Open Perspective icon ( Open Perspective icon ) in the perspectives tab to access the list of available perspectives.

    Figure 7.1. Fuse Integration perspective

    Fuse Integration perspective layout
    Note
    To make it easy to access a Camel Context .xml file, especially when a project consists of multiple contexts, the tooling lists them in the Camel Contexts folder, beneath the project's root folder in Project Explorer; for example:
  2. Drag the Diagram View tab and the Shell tab, located to the left of the JMX Navigator tab, and drop them to the right of the JMX Navigator tab, as shown in Figure 7.2.

    Figure 7.2. Fuse Integration perspective rearranged

    Fuse Integration perspective rearranged layout
    This layout will provide more space for Diagram View to display the route's nodes in a graphical representation, enabling you to visually trace the path that messages take in traversing the routing context.

Starting message tracing

To start message tracing on the CBRroute project:
  1. In Project Explorer, expand the CBRroute project to expose the src/main/resources/OSGI-INF/blueprint/camelContext.xml file.
  2. Select Run As → Local Camel Context (without tests) from the camelContext.xml file's context menu.
  3. In JMX Navigator, expand Local Processes.
  4. Double click Local Camel Context[Id][Disconnected] to connect to it and expand the elements of your route, as shown in Figure 7.3, “Route elements in JMX Navigator”.

    Figure 7.3. Route elements in JMX Navigator

    Route expansion in Fuse JMX Navigator
  5. Right-click the blueprintContext node to open the context menu, and select Start Tracing.
    The tooling displays a graphical representation of your route in Diagram View, as shown in Figure 7.4.

    Figure 7.4. Routes' graphical representation

    Diagram View: graphical representation of the routes

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), as shown in Figure 7.5, “Message files in CBRroute project”.

    Figure 7.5. Message files in CBRroute project

    Message source files in CBRroute project
  2. Drag message1.xml and drop it on the blueprintContext>Endpoints>file>src/data?noop=true node in JMX Navigator, as shown in Figure 7.6.

    Figure 7.6. Local Camel Context tree expanded to input source node

    Local Camel Context tree expanded to source file input node
    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 blueprintContext node in JMX Navigator.
    Note
    The Local Camel Context[xxx] tree collapses to the blueprintContext node after you drop the next message on the input src 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 to persist across all message traces.
  1. Switch from Console to Messages View.
  2. Click the blueprintContext 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 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, as shown in Figure 7.7.

    Figure 7.7. Configure Columns defaults

    Configure Columns defaults
    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 items as shown in Figure 7.8.

    Figure 7.8. Configure Columns set

    Configure Columns set
    These items 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 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, as shown in Figure 7.9.

    Figure 7.9. Message trace selected

    Message trace selected
    The tooling displays the details about a message trace (including message headers when they are set) in the top half of the Properties panel and the contents of the message instance in the bottom half of the Properties panel. 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, as shown in Figure 7.10.

    Figure 7.10. Diagram View: message trace node

    Diagram View: message trace node

Finishing up

  1. Drag message2.xml and drop it on theblueprintContext>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 button) on top, right of the panel's menu bar to populate the view with message2.xml's message traces.
    Note
    You can repeat Step 2 through Step 2 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 button) on the panel's menu bar to populate Messages View with the new message traces.
    As shown in Figure 7.11, 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.

    Figure 7.11. Fuse Integration perspective's message tracing components

    Message tracing in Fuse Integration perspective
    Hovering over the displayed metrics reveals additional metrics about message flow, as shown in Figure 7.12.

    Figure 7.12. Additional message metrics

    Additional message metrics revealed in Diagram View
    • 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 blueprintContext 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 with it, as described in Chapter 8, To Test a Route with JUnit.