Chapter 23. Tracing Routes

Debugging a route often involves solving one of two problems:

  • A message was improperly transformed.
  • A message failed to reach its destination endpoint.

Tracing one or more test messages through the route is the easiest way to discover the source of such problems.

The tooling’s route tracing feature enables you to monitor the path a message takes through a route and see how the message is transformed as it passes from processor to processor.

The Diagram View displays a graphical representation of the route, which enables you to see the path a message takes through it. For each processor in a route, it also displays the average processing time, in milliseconds, for all messages processed since route start-up and the number of messages processed since route start-up.

The Messages View displays the messages processed by a JMS destination or route endpoint selected in the JMX Navigator tree. Selecting an individual message trace in the Messages View displays the full details and content of the message in the Properties view and highlights the correspoding node in the Diagram View.

Tracing messages through a route involves the following steps:

  1. Section 23.1, “Creating test messages for route tracing”
  2. Section 23.2, “Activating route tracing”
  3. Section 23.3, “Tracing messages through a routing context”
  4. Section 23.4, “Deactivating route tracing”

23.1. Creating test messages for route tracing

Overview

Route tracing works with any kind of message structure. The Fuse Message wizard creates an empty .xml message, leaving the structuring of the message entirely up to you.

Note

If the folder where you want to store the test messages does not exist, you need to create it before you create the messages.

Creating a new folder to store test messages

To create a new folder:

  1. In the Project Explorer view, right-click the project root to open the context menu.

  2. Select New → Folder to open the New Folder wizard.

    The project root appears in the Enter or select the parent folder field.

  3. Expand the nodes in the graphical representation of the project’s hierarchy, and select the node you want to be the parent folder.
  4. In the Folder name field, enter a name for the new folder.

  5. Click Finish.

    The new folder appears in the Project Explorer view, under the selected parent folder.

    Note

    If the new folder does not appear, right-click the parent foler and select Refresh.

Creating a test message

To create a test message:

  1. In the Project Explorer view, right-click the project to open the context menu.
  2. Select New → Fuse Message to open the New File wizard.
  3. Expand the nodes in the graphical representation of the project’s hierarchy, and select the folder in which you want to store the new test message.
  4. In the File name field, enter a name for the message, or accept the default (message.xml).

  5. Click Finish.

    The new message opens in the XML editor.

  6. Enter the message contents, both body and header text.

    Note

    You may see the warning, No grammar constraints (DTD or XML Schema) referenced in the document, depending on the header text you entered. You can safely ignore this warning.

23.2. Activating route tracing

Overview

You must activate route tracing for the routing context before you can trace messages through that routing context.

Procedure

To activate tracing on a routing context:

  1. In the JMX Navigator view, select the running routing context on which you want to start tracing.

    Note

    You can select any route in the context to start tracing on the entire context.

  2. Right-click the selected routing context to open the context menu, and then select Start Tracing to start the trace.

    If Stop Tracing Context is enabled on the context menu, then tracing is already active.

23.3. Tracing messages through a routing context

Overview

The best way to see what is happening in a routing context is to watch what happens to a message at each stop along the way. The tooling provides a mechanism for dropping messages into a running routing context and tracing the path the messages take through it.

Procedure

To trace messages through a routing context:

  1. Create one or more test messages as described in Section 23.1, “Creating test messages for route tracing”.

  2. In the Project Explorer view, right-click the project’s Camel context file to open the context menu, and select Run As → Local Camel Context (without Tests).

    Note

    Do not run it as Local Camel Context unless you have created a comprehensive JUnit test for the project.

  3. Activate tracing for the running routing context as described in Section 23.2, “Activating route tracing”.
  4. Drag one of the test messages from the Project Explorer view onto the routing context’s starting point in the JMX Navigator view.

  5. In the JMX Navigator view, select the routing context being traced.

    The tooling populates the Messages View with message instances that represent the message at each stage in the traced context.

    The Diagram View displays a graphical representation of the selected routing context.

  6. In the Messages View, select one of the message instances.

    The Properties view displays the details and content of the message instance.

    In the Diagram View, the route step corresponding to the selected message instance is highlighted. If the route step is a processing step, the tooling tags the exiting path with timing and processing metrics.

  7. Repeat this prodedure as needed.

23.4. Deactivating route tracing

Overview

When you are finished debugging the routes in a routing context, you should deactivate tracing.

Important

Deactivating tracing stops tracing and flushes the trace data for all of the routes in the routing context. This means that you cannot review any past tracing sessions.

Procedure

To stop tracing for a routing context:

  1. In the JMX Navigator view, select the running routing context for which you want to deactivate tracing.

    Note

    You can select any route in the context to stop tracing for the context.

  2. Right-click the selected routing context to open the context menu, and then select Stop Tracing Context.

    If Start Tracing appears on the context menu, tracing is not activated for the routing context.