Debugging EPL Applications

You can debug Apama applications written in EPL in Apama Plugin for Eclipse. As is the case when debugging other applications in Eclipse, when you debug EPL applications, you can set breakpoints to suspend the application at specific points, examine the contents of variables, and step through the application.

The basic tasks involved in debugging an EPL application in Apama Plugin for Eclipse are:

  1. Set breakpoints in the Developer perspective.
  2. Create a debug launch configuration for the project.
  3. Review the executing application in the Debug perspective, examining information such as the call stack, context status, and variable values.

Adding breakpoints

You can add breakpoints to any of the EPL files included in the project. To add a breakpoint to an EPL file:

  1. In the Developer perspective open the EPL file in which you want to add a breakpoint.

  2. Double click in the left margin of the desired line in the EPL file or right-click in the left margin and select Toggle Breakpoint from the pop-up menu. The breakpoint is indicated by a solid blue circle in the left margin.

  3. Repeat Step 1 and Step 2 for each breakpoint you want to set.

Note, when debugging an application on a remote machine, breakpoints are supported only inside EPL actions of monitors and events. Breakpoints inside listeners of actions or breakpoints outside of actions are not supported. See Debugging a remote application.

Launching a debug session

If a Debug Configuration has been defined for the Apama project, start a debugging session as follows. (If you need to create a Debug Configuration, see Creating a debug configuration)

  1. From the Apama Plugin for Eclipse menu, select Run > Debug Configurations.

  2. From the Debug Configuration dialog, select the desired Debug Configuration and click Debug. The Confirm Perspective Switch dialog appears.

  3. Click Yes to display the Debug Perspective (and add a check to the Remember my decision check box if desired). The Debug perspective appears.

When debugging an EPL application, the Debug perspective is similar in operation to the standard Eclipse Debug perspective and includes the Debug, Breakpoints, and Variables views.

Creating a debug configuration

To create a new debug configuration

  1. From the Apama Plugin for Eclipse menu, select Run > Debug Configurations. The Profile configurations wizard starts.

  2. In the left pane, select Apama Application and click the New launch configuration button (Icon)).

  3. In the right pane, on the Apama Project tab, specify the Name and the Project.

  4. If you are going to debug an application running on a remote correlator:

    1. Select the Components tab.

    2. Click Add and select Add Correlator.

    3. In the Correlator Configuration wizard, on the Correlator Arguments tab, specify the Host, Port, and other Options.

      Info
      When creating a debug launch configuration, you do not need to specify the -g option in the Correlator Arguments tab. When you select Run > Debug, Apama Plugin for Eclipse automatically starts the correlator with the -g option, which disables optimizations that hinder debugging. However, if you use Apama Plugin for Eclipse to debug in a remote correlator, you must ensure that the remote correlator was started with the -g option. You cannot debug in a correlator that was started without specification of the -g option. See the options information in Starting the correlator.

    4. If necessary, specify any initialization options on the Initialization tab.

    5. Click OK.

  5. Click Debug. The Confirm Perspective Switch dialog opens.

  6. Click Yes. Apama Plugin for Eclipse switches to the Debug perspective.

Debugging a remote application

In Apama Plugin for Eclipse, you can debug an Apama application running in a correlator on a remote machine. The correlator on the remote machine must have been started with the -g option, which disables optimizations that interfere with debugging.

Info
When debugging a remote application, breakpoints are supported only inside actions of monitors and events. Breakpoints inside listener actions or outside of actions are not supported.

To debug an application on a remote machine

  1. Start the application on the remote machine.

  2. In Apama Plugin for Eclipse on the local machine where you will do the debugging, select Run > Debug Configurations. This displays the Debug Configurations wizard.

  3. In the Debug Configurations wizard, in the left pane select Remote Apama Application, and click the New launch configuration button (Icon).

  4. In the right pane, on the Apama Project tab, specify the following:

    1. The Name of the debug configuration and the Project on the local machine where the debugging session is being run. The application in the project should match the application that is being debugged.

    2. The Host and the Port of the correlator running on the remote machine.

    3. If desired, click Test Connection to verify that the connection to the correlator on the remote machine can be made.

  5. If desired, on the Source tab, add any needed resources. Generally, the project on the local machine will contain all the necessary resources.

  6. Click Debug. The Confirm Perspective Switch dialog opens.

  7. Click Yes. Apama Plugin for Eclipse switches to the Debug perspective. 5. Click OK.

  8. Click Debug. The Confirm Perspective Switch dialog opens.

  9. Click Yes. Apama Plugin for Eclipse switches to the Debug perspective.

Debug view for an EPL application

The Debug view shows the call stack and status of current contexts in the Apama application. When execution reaches a breakpoint, the current context in the Debug view is highlighted.

Also, when a breakpoint is reached, the EPL editor indicates the breakpoint in the code with an arrow in the left margin.

When a stack frame is highlighted in the Debug view, the Variable view displays the names and values of the associated variables, see Variables view for an EPL application.

See the Eclipse online help for detailed information on this view.

Breakpoints view for an EPL application

The Breakpoints view lists the breakpoints you have set in the project.

Double-clicking a breakpoint displays the line in the EPL file that contains the breakpoint in the EPL editor. In the Breakpoints view, you can enable and disable the listed breakpoints.

See the Eclipse online help for detailed information on this view.

Variables view for an EPL application

The Variables view displays information about the variables associated with the stack frame that is currently selected in the Debug view.

The variables can be expanded to show their fields. The detail pane in the area at the bottom of the view displays text. For a variable of a primitive type, this is the value of the object. For a complex variable, such as a sequence, dictionary, or event, it is the text representation of the object as returned by the object’s toString() method.

For complex variables, you can click the Show Logical Structure button (Icon) to expand the variables to show their sub-values.

If you want to change the layout of the display, click the drop-down menu button (Icon) at the top right of the Variables view. From the resulting menu, select Layout and then the desired layout option.

See the Eclipse online help for detailed information on this view.

Command-line debugger

You can also use Apama’s engine_debug tool to control execution of your EPL code in the correlator and inspect correlator state. This tool is a correlator client that runs a single command from the command line. It is not an interactive command-line debugger. The interactive debugger in Apama Plugin for Eclipse is more useful during the development of an application. In general, the command-line engine_debug tool is expected to be most useful during or after deployment of your application.

For more information on engine_debug, see Using the command-line debugger.