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:
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.
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:
- In the Project Explorer view, right-click the project root to open the context menu.
Select New
Folder to open the New Folder wizard. The project root appears in the Enter or select the parent folder field.
- Expand the nodes in the graphical representation of the project’s hierarchy, and select the node you want to be the parent folder.
- In the Folder name field, enter a name for the new folder.
Click Finish.
The new folder appears in the Project Explorer view, under the selected parent folder.
NoteIf the new folder does not appear, right-click the parent foler and select Refresh.
Creating a test message
To create a test message:
- In the Project Explorer view, right-click the project to open the context menu.
-
Select New
Fuse Message to open the New File wizard. - 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.
-
In the File name field, enter a name for the message, or accept the default (
message.xml). Click Finish.
The new message opens in the XML editor.
Enter the message contents, both body and header text.
NoteYou 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:
In the JMX Navigator view, select the running routing context on which you want to start tracing.
NoteYou can select any route in the context to start tracing on the entire context.
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:
- Create one or more test messages as described in Section 23.1, “Creating test messages for route tracing”.
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). NoteDo not run it as Local Camel Context unless you have created a comprehensive JUnit test for the project.
- Activate tracing for the running routing context as described in Section 23.2, “Activating route tracing”.
- Drag one of the test messages from the Project Explorer view onto the routing context’s starting point in the JMX Navigator view.
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.
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.
- 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.
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:
In the JMX Navigator view, select the running routing context for which you want to deactivate tracing.
NoteYou can select any route in the context to stop tracing for the context.
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.
