Debugging Routing Contexts

Table of Contents

Setting Breakpoints
Running the Camel Debugger
Stopping the Camel Debugger
Changing Variable Values
Adding Variables to the Watch List
Disabling Breakpoints in a Running Context

The Camel debugger includes many features for debugging locally and remotely running routing contexts:

Setting conditional and unconditional breakpoints on nodes in the route editor
Autolaunching the debugger and switching to the Debug perspective
Interacting with the running routing context:
- Switch between breakpoints to quickly compare variable values of message instances
- Examine and change the value of variables of interest
- Add variables of interest to the watch list to track them throughout the debug session
- Disable and re-enable breakpoints on-the-fly
- Track message flow graphically in the routing context runtime
- Examine console logs to track Camel and debugger actions

	Note
	Before you can run the Camel debugger, you must set breakpoints on the nodes of interest displayed on the route editor’s canvas. Then you can run the Camel debugger on a project’s routing context `.xml` file to find the logic errors in it and fix them. Invoking the Camel debugger runs the routing context in debug mode and opens the Debug perspective (Debug Perspective).

Setting Breakpoints

Overview

To set breakpoints, your project’s routing context .xml file must be open in the route editor’s Design tab.

The Camel debugger supports two types of breakpoints:

Unconditional breakpoints — triggered whenever one is encountered during a debugging session
Conditional breakpoints — triggered only when the breakpoint’s specified condition is met during a debugging session

	Note
	You cannot set breakpoints on consumer endpoints or on `when` or `otherwise` nodes.

Setting unconditional breakpoints

With your routing context displayed on the canvas in the Design tab:

Select a node whose state you want to examine during the debugging session.
Click its icon to set an unconditional breakpoint.
Repeat these steps for each node on which you want to set an unconditional breakpoint.

Setting conditional breakpoints

With your routing context displayed on the canvas in the Design tab:

Select a node whose state you want to examine during the debugging session.
Click its icon to set a conditional breakpoint and to open the Edit the condition and language of your breakpoint… dialog:
Click the Language drop-down menu and select the expression language to use to create the condition that will trigger the breakpoint.
Fuse Tooling supports twenty-four expression languages. Some of these languages provide variables for creating conditional expressions, while others do not.
Click Variables to display a list of the selected language’s supported variables.
If a list appears, select in sequence one or more of the variables to create the condition for triggering the breakpoint. The variables you select appear in the Condition text box.
If appears, enter the expression directly into the Condition text box.
Repeat steps [condBpFirst] through [condBpLast] for each node on which you want to set a conditional breakpoint.

Disabling breakpoints

You can temporarily disable a breakpoint, leaving it in place, then enable it again later. The resume co button skips over disabled breakpoints during debugging sessions.

To disable a breakpoint, select the node on the canvas and click its gray dot icon. The breakpoint turns gray, indicating that it has been disabled.

To enable a disabled breakpoint, select the node on the canvas and click its green dot icon. Depending on whether the disabled breakpoint is conditional or unconditional, it turns yellow or red, respectively, to indicate that it has been re-enabled.

	Note
	You can also disable and re-enable breakpoints during debugging sessions. For details, see Disabling Breakpoints in a Running Context.

Deleting breakpoints

You can delete individual breakpoints or all breakpoints.

To delete individual breakpoints — in a route container, select the node whose breakpoint you want to delete, and click its icon.
To delete all breakpoints in a particular route — right-click the target route’s container, and select Delete all breakpoints.
To delete all breakpoints in all routes — right-click the canvas, and select Delete all breakpoints.

Running the Camel Debugger

Table of Contents

Debugging a locally running routing context
Debugging a remotely running routing context

You can run the Camel debugger on locally running routing contexts and on remotely running routing contexts. The same basic features and functionality are available in both debugging modes.

Local debugging — runs the debugger on the routing context running in the same JVM with Fuse Tooling. This mode is activated by selecting the project’s routing context in the Project Explorer view and selecting Debug As > Local Camel Context from the context menu.
Remote debugging — runs the debugger on a routing context running in a separate JVM either on the local machine or on a remote machine. This mode requires a supported runtime server installed on the local machine or on an accessible remote machine. It is activated by creating and running a debug launch configuration that specifies the remote runtime’s connection details.

	Note
	If your project contains Java code, you can use the standard Eclipse Java debugging tools to debug it. For local debugging, it is automatically available. For remote debugging, you need to use the Remote Camel Context and Java launch option (see Debugging a remotely running routing context).

	Note
	You must set breakpoints in your routing context file before you can start the Camel debugger.

Debugging a locally running routing context

Procedure

In the Project Explorer view, select the routing context file you want to debug.
Right-click the selected file to open the context menu, and then select Debug As > Local Camel Context.
Fuse Tooling builds the Camel route, starts Apache Camel, starts the routing context, enables JMX, starts the route(s) in the routing context, adds the breakpoints to the nodes, and enables the Camel debugger.
The Camel debugger suspends execution of the routing context at the first breakpoint hit (received a message), and prompts you to indicate whether you want it to open the Debug perspective.

Click Yes to open the Debug perspective.

The Debug perspective opens with the routing context suspended at the first breakpoint encountered in the running routing context.

	Important
	Breakpoints are held for a maximum of five minutes, after which debugging automatically resumes, moving on to the next breakpoint or to the end of the routing context.

	Note
	To see the console output, open the Console view if it was not open when you switched perspectives.

	Note
	By default, the Debug perspective displays the Outline view, which provides the means to switch between separate routes in a running routing context. If your routing context contains a single route, closing the Outline view frees space to expand the other views, making it easier to access and examine debugger output.

Watching message exchanges progress through the routing context

Click stepover co (Step Over) to jump to the next node of execution in the routing context. Click resume co (Resume) to continue execution at the next active breakpoint in the routing context.

Debugging a remotely running routing context

Prerequisites

Access to a JBoss Fuse runtime in one of the following ways:
- Install a JBoss Fuse server on your local machine and edit its FUSE_HOME/etc/users.properties file to activate the admin user. For details, see Adding a Server.
- Be able to access a JBoss Fuse server that is installed on a remote machine. You must know its connection details, including the credentials of the admin user.

Create a new Fuse Integration project, see Configuring project basics. In the Fuse Integration project:

Select the Camel version that matches the version of the JBoss Fuse server runtime.

Create an empty Blueprint DSL project or use one of the JBoss Fuse pre-defined templates with Blueprint DSL.

	Note
	Though not a requirement, it is a good idea to verify that you can run the project’s routing context successfully as a `Local Camel Context`. For details, see Running routes as a local Camel context.

	Note
	The examples in Setting up and starting remote debugging are based on the JBoss Fuse > Content Based Router pre-defined template and a Red Hat JBoss Fuse 6.3.0 runtime.

In Red Hat JBoss Developer Studio:

Add the JBoss Fuse server to the Servers view. For details, see Adding a Server.
Start the JBoss Fuse server. For details, see Starting a Server.

Publish your project to the JBoss Fuse Runtime server. For details, see Publishing Fuse projects automatically when resources change.

	Note
	You cannot deploy a Fuse Integration project to a JBoss Fuse server running on a remote host from inside JBoss Developer Studio. Instead, you deploy the project’s bundle directly on the remote host using one of two supported deployment methods (for details, see ).

Verify that the project’s bundle is deployed and active. For details, see Verifying the project was published to the server.
Stop the JBoss Fuse Runtime server. For details, see Stopping a Server.

Setting up and starting remote debugging

With the project deployed on JBoss Fuse and the server stopped, you need to set up and start remote debugging as follows:

Start JBoss Fuse in debug mode outside of JBoss Developer Studio.
In JBoss Developer Studio, set breakpoints on nodes in the project’s routing context, which is open in the route editor.
Create a remote Camel context debug configuration and run it.
Connect to JBoss Fuse runtime in the JMX Navigator view.
Drop test messages in the JMX Navigator view on the input node of the Camel route running inside the JBoss Fuse runtime.
Use any of the Camel debugger’s tools for debugging routes.

Procedure

To set up and start remote debugging:

Open a terminal outside of JBoss Developer Studio, and enter
```
$ [FUSE_HOME]/bin/fuse debug
```
Wait for the JBoss Fuse splash screen to appear, and then return to the Fuse Integration perspective in JBoss Developer Studio.
In the tooling’s route editor, with the project’s routing context open in the Design tab, set breakpoints on the nodes of interest. For details, see Setting Breakpoints.
In the Project Explorer view, right-click the project’s root and select menu:[Debug As > Debug Configurations] to open the Debug Configurations wizard:
In the configuration type pane, select either Remote Camel Context or Remote Camel Context and Java , and then click :
For both the Remote Camel Context and Remote Camel Context and Java options, you need to specify configuration details on the Camel and JMX tabs.
For the Remote Camel Context and Java option only, you also need to specify configuration details on the Connect tab.
Note
Unless your project contains Java code that you want to debug using the standard Eclipse Java debugging tools, select the Remote Camel Context option.
In the Name field, enter a name for the new launch configuration.
On the Camel tab, click the Browse button to locate the project’s routing context .xml file in the Open Resources dialog:
Note
When you select a file in the Matching items pane, the tooling displays the file’s location, relative to the project root, at the bottom of the pane.
In the Matching items pane, select your project’s routing context file from the list, and then click OK.
The tooling inserts the file’s path into the Select Camel Context file field:

Click the JMX tab:

Edit the JMX connection details as follows:

JMX Uri — change :9011/jmxrmi to :1099/karaf-root
If the JBoss Fuse server is running on a remote host, replace localhost with the DNS name or IP address of the remote host.
JMX User — enter admin.

JMX Password — enter admin.

	Important
	The values shown for JMX User and JMX Password are the JBoss Fuse admin user defaults, stored in the `FUSE_HOME/etc/users.properties` file. If your setup is different, enter the values specific to it.

If you are creating a Remote Camel Context debug launch configuration, you are done. Skip to [debugCfgGo].

Click the Connect tab:
Change the Port value from 8000 to 5005. Leave each of the other properties as is.
Click Apply and then click Debug.
In the JMX Navigator view, double-click JBoss Fuse [xxx] [Disconnected] to connect to it, and then expand its tree:
In the Project Explorer view, drag a test message from src/test/resources/data and drop it on the cbr-example-context/Endpoints/file/work/cbr/input folder in the JMX Navigator view.
When the message hits the first breakpoint that is set in the routing context, the tooling asks you to switch to the Debug perspective:

Click Yes.

At this point, you can use any of the Camel debugger’s tools to debug your routing context.

	Note
	In remote debugging sessions, the Console view does not display log output.

	Note
	When one message reaches the end of the routing context, the debugger is suspended. To continue debugging, switch back to the Fuse Integration perspective and drop another message on the input node in the JMX Navigator view. Each time you do so, the tooling asks you to confirm the switch to the Debug perspective.

Stopping the Camel Debugger

Overview

The way to stop the Camel debugger depends on the mode in which it is running:

Local debugging (Debugging a locally running routing context)
To stop the Camel debugger, click on the menu bar once if the debugging session has ended. Otherwise, click twice: once to terminate the currently running node thread and once to terminate the Camel Context thread (both displayed in the Debug view).
Note
Terminating the Camel debugger also terminates the console but does not clear its output. To clear the output, click (Clear Console) on the Console view’s menu bar.
Remote debugging (Debugging a remotely running routing context)
To stop the Camel debugger, select the [Remote Camel Context] thread or the [Remote Camel Context and Java] thread in the Debug view, and then click on the menu bar.
Note
Terminating the Camel debugger does not close the connection to the remote runtime server in the Servers view nor in the JMX Navigator view.

Closing the Camel debugger

After you have finished debugging your project, you may want to close the Debug perspective to make more space for your workbench.

To do so, right-click Debug perspective icon on the right side of the JBoss Developer Studio toolbar, and then select Close.

Changing Variable Values

Overview

When the Camel debugger hits a breakpoint, the Variables view displays the values of all variables available at that point in the routing context. Some variables are editable, allowing you to change their value. This enables you to see how the application handles changes in program state.

	Note
	Not all variables are editable. The context menu of editable variables displays the Change Value… option.

Procedure

To change the value of a variable:

If necessary, start the debugger. See Running the Camel Debugger.
In the Variables view, select a variable whose value you want to change, and then click its Value field.
The variable’s value field turns a lighter shade of blue, indicating that it is in edit mode.
Note
Alternatively, you can right-click the variable to open its context menu, and select Change Value… to edit its value.
Enter the new value and then click Enter.
The Console view displays an INFO level log entry noting the change in the variable’s value (for example, Breakpoint at node to1 is updating message header on exchangeId: ID-dhcp-97-16-bos-redhat-com-52574-1417298894070-0-2 with header: Destination and value: UNITED KINGDOM).
Continue stepping through the breakpoints and check whether the message is processed as expected. At each step, check the Debug view, the Variables view, and the Console output.

Adding Variables to the Watch List

Overview

By adding variables to the watch list, you can focus on particular variables to see whether their values change as expected as they flow through the routing context.

Procedure

To add a variable to the watch list:

If necessary, start the debugger. See Running the Camel Debugger.
In the Variables view, right-click a variable you want to track to open the context menu.
Select Watch.
A new view, Expressions, opens next to the Breakpoints view. The Expressions view displays the name of the variable being watched and its current value, for example:
Repeat [watch1] and [watch2] to add additional variables to the watch list.
Note
The variables you add remain in the watch list until you remove them. To stop watching a variable, right-click it in the list to open the context menu, and then click Remove.
With the Expressions view open, step through the routing context to track how the value of each variable in the watch list changes as it reaches each step in the route.

Disabling Breakpoints in a Running Context

Overview

You can disable and re-enable breakpoints in a running routing context in the Breakpoints view.

When a breakpoint is disabled, the resume co button causes the debugger to skip over it during the debugging session.

Disabling and enabling breakpoints in Breakpoints view

The Breakpoints view opens with all set breakpoints enabled.

To disable a breakpoint, clear its check box.

For each breakpoint you disable, the Console view displays an INFO level log entry noting that it has been disabled (for example, Removing breakpoint log2). Likewise, for each breakpoint you re-enable, the Console view displays an INFO level log entry noting that it has been enabled (for example, Adding breakpoint log2).

	Note
	To re-enable a disabled breakpoint, click its check box. The Console view displays an `INFO` level log entry noting that the breakpoint has been added to the selected node.