04. Debugging Workflows


Debugging can be tricky with Kepler workflows. There are multiple levels that need to be considered in the executing/debugging process, the Kepler workflow, the Java virtual machine that Kepler is running in, and any outside codes that are called from Kepler.

A common debugging scenario is a workflow which runs an external code. The workflow crashes at some point and Kepler stops running with little or no diagnostic information. The user now has to find out what caused the crash, was it a fault the their code which is called from Kepler, was it a fault in the calling interface between Kepler and the code, was it a problem with the Kepler workflow, or where there issue with the Java virtual machine (such as running out of memory, etc...).

Clearly as there are multiple levels in the workflow system there are multiple areas that need debugging. Kepler has some in-built debugging features such as allowing users to listen to actors (which is briefly describe in the next section, as well as in the Basic Kepler Training) that exposes some of the messages sent between actors, and animating workflow (which is described below).

There are also tools for debugging workflows, including using the Eclipse IDE and using functionality provided through Kepler version 2. All these techniques will be outlined in the next sections of this tutorials.

Basic Kepler debugging

Animating Workflows

One of the simplest tools for debugging in Kepler is Animating workflows. This allows Kepler to display which actors are being used whilst the workflow is running, and add a specified delay between firing actors to slow down the workflow execution and enable users to see which are being called (without the delay actors often execute too quickly to be visible during the workflow).

Animate workflow exercise

1. Start Kepler application by issuing:


2. Open "Hello world debug" workflow by issuing: File -> Open and navigate to:


3. Select the "Animate at Runtime..." option from the Tools menu as shown in the image below.

4. Enter a sensible delay, such as 1000, into the "Delay for Animation" box which appears (as shown below).

5. Press the "Play" button to run the workflow

The workflow will run, highlighting the actor that is currently executing in red, as in the image below. Following the workflow through until it has finished.

Listening to Actors
Basic debugging exercise

In this exercise you will execute simple Kepler workflow with Debug information. In order to this follow the instructions:

1. Start Kepler as in the above example.

2. Open "Hello world debug" workflow by issuing: File -> Open and navigate to:


3. After workflow is opened, "Right-click" HelloWorldDebug actor and choose "Listen to actor"

4. Run the workflow. The workflow should generate output within Display actor and should print debug information generated by the "Hello World Debug" actor in a separate display window.

Debugging with Eclipse

Kepler is a Java program and as such can be debugged as any standard Java program. One of the easiest ways to do this is using the Eclipse Integrated Development Environment (IDE). Eclipse allows the running of Java programs in debug mode where breakpoints can be used to run the program up to defined points in the program and then wait for user input. You can also monitor the status of variables, etc..., along with other aspects of the program. Where, the Kepler program allows you to monitor messages that are generated within actors, Eclipse allows for users to interrogate and examine the actual code that actors are constructed from whilst the workflow is running to identify errors and problems.

To debug a Kepler workflow using eclipse you need to obtain and install the Kepler source code in such a way as Eclipse can load and use it. Fortunately the Kepler developers have provided some tools/features to allow users to do this.

For debugging with eclipse, need to download and install eclipse. Need to use Java 1.6. The following documents how to build kepler for eclipse: https://kepler-project.org/developers/teams/build/documentation/build-system-instructions. Need to have ant installed (version 1.7 is fine). Will also need JAVA_HOME and ANT_HOME set, and have ANT_HOME/bin and JAVA_HOME/bin on PATH. Also need some svn client installed (i.e. subversion from tigrus http://subversion.apache.org/packages.html). Then build, either for Kepler-2.0 (using -Dsuite=kepler) or Kepler-1.0 (using -Dsuite=kepler-1.0). Can use either for eclipse debugging.

Debugging with Kepler 2.0

Whilst the ITM is currently using Kepler-1.0, the latest version of Kepler (Kepler-2.0) provides more built-in debugging functionality. In addition to what was available in Kepler-1.0 users can also examine the status and data at each port in a workflow.

The debugging we're going to do does not use the Kepler user library actors (i.e. not from the box on the left hand side). Instead it uses an attribute which changes the behaviour of the workflow and enables data and status information to be displayed to the screen. The specific attribute used is called "ptolemy.vergil.actor.lib.MonitorReceiverContents" and its use will be described in the next exercise.

Kepler 2.0 Debugging

To undertake such debugging follow these steps:

1. You'll need to download Kepler-2.0. You can do this on the gateway using the following command:


2. Install Kepler-2.0 by running the following commands:
*chmod 755 Kepler-2.0-linux.jar

Then following the on-screen instructions and Kepler will be installed.

3. To run Kepler change to the Kepler directory (i.e. cd Kepler-2.0) and run:

4. Open an example workflow, such as workflows/simple/array_loop.xml from the demos directory

5. Instantiate the attribute required by selecting the "Tools" menu and clicking the "Instantiate Attribute" as shown below (be careful to choose "Instantiate Attribute" rather than "Instantiate Component")

6. In the "Instaniate Attribute" pop-up window replace the current text in the "Class Name" field with this text: "ptolemy.vergil.actor.lib.MonitorReceiverContents" and click Ok.

7. This will place a blue box (highlighted by yellow) onto the workflow and add some extra text (brackets such as these []) to each of the ports on the actors in the workflow. These will display the data that is present on the input or outputs during the execution of the workflow.

8. Animate the workflow as described in the "Animate workflow exercise".

9. Play the workflow and you should see control passing through the actors and the data that is flowing through the workflow. If it is difficult to work out what is happening try increasing the delay in the animation of the workflow to see if that helps.

The debugging we're going to do does not use the Kepler user library actors (i.e. not from the box on the left hand side). So need to "instantiate attribute" (not "instantiate component"), class name is "ptolemy.vergil.actor.lib.MonitorReceiverContents". This is just a flag to tell the director that it should monitor ports. So can just add this attribute to an already created workflow in Kepler-2.0 and it will turn the debugging on. So this shows the data following through actors by displaying the data in inputs or outputs which are remaining to be processed. It also highlights the issue that an actor can only fire if all attached inputs have a value waiting. It also works with composite actors, as it works at the level it is placed and below (i.e. it makes sense to place this at the highest workflow level). It also does not really create any performance degradation. You can use this at the same time as the eclipse debugging.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.