Using the command-line debugger

The engine_debug tool lets you control execution of 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 executable for this tool is located in the Apama/bin directory.

Before you run the engine_debug tool, specify the -g option when you start the correlator. Specification of this option disables some correlator optimizations. If you run the engine_debug tool and you did not specify the -g option when you started the correlator, the optimizations hinder the debugging process. For example, the correlator might simultaneously execute multiple statements over multiple lines even if you are using debugger commands to step through the program line by line.

Synopsis

To debug applications on a running correlator, run the following command:

engine_debug [ [ global-options ] [command [options]]... ]

To obtain a usage message, run the command with the help option.

Description

Debugging a running correlator has some effect on the other programs that connect to that correlator. While you pause a correlator, the expected behavior of connected components is as follows:

Sending events to the correlator continues to put events on the input queue of each public context. However, since the input queues are not being drained, if an input queue fills up, this will block senders, including the engine_send tool and adapters.
The correlator sends out any events on its output queue. When the output queue is empty, receivers no longer receive events; no contexts are sending events.
Other inspections of the correlator proceed as normal. For example, engine_watch, engine_management, and profiling data.
You can shut down the correlator.
You can inject monitors while the correlator is stopped. They will not run any of the onload() or similar code until the correlator resumes, but the inject call should succeed.
Java applications continue to run completely independently of whether the correlator is stopped.
All other requests block until the correlator resumes processing. This includes dumping correlator state, loading, and changing debug or profiling state.

The engine_debug tool is stateless. Consequently, during debugging, you can have multiple concurrent connections to the same correlator.

Debug commands

The ordering of arguments to engine_debug commands works as follows:

All arguments before the first command apply to all commands in that command line. This is useful for setting the host and port if you are not using the local defaults.
All arguments following a command apply to only that command and they override any applicable arguments specified before the first command.
The arguments to a particular command can be in any order
When there are multiple commands in a line, the debugger executes them in the order in which they are specified. Execution continues until either all complete, or one fails, which prevents execution of any subsequent commands.

The engine_debug tool takes the following commands as options:

Abbreviation	Command	Description
`h [command]`	`help [command]`	Displays a usage message. To obtain help for a particular `engine_debug` command, specify that command.
`p`	`status`	Displays the current debugger state, and position if stopped.
`ha`	`hashes`	Lists injected files and their hashes.
`si`	`stepinto`	Steps into an action.
`sot`	`stepout`	Steps out of an action.
`sov`	`stepover`	Steps over an instruction.
`r`	`run`	Begins processing instructions.
`b`	`stop`	Stops processing instructions.
`w [-to int]`	`wait [--timeout timeout]`	Waits for the correlator to stop processing instructions. Specify an integer that indicates the number of seconds to wait. The debugger waits forever if you do not specify a timeout. See The wait command for more information.
`s`	`stack [--context contextid] \| [--frame frameid]`	Displays current stack information for all contexts. The output includes the frame ID associated with each variable. To display stack information for only a particular context, specify the `--context` argument. To display stack information for only a particular frame, specify the `--frame` argument.
`i`	`inspect --instance monitorinstance \| --instance monitorinstance --frame frameid \| --instance monitorinstance --variable variablename \| --instance monitorinstance --frame frameid --variable variablename \| --frame frameid \| --frame frameid --variable variablename`	Displays the value of one or more variables. Specify a monitor instance and/or a frame ID and/or a variable name to display a list of variables in that monitor or in a particular monitor frame, or to display the value of a particular variable. Obtain monitor instance IDs from `engine_inspect` output or correlator log statements. Obtain frame IDs from `engine_inspect stack` output.
`c`	`context [--context contextid]`	Displays information about all contexts in the correlator or about only the context you specify. Information displayed includes context name, context ID, monitor instances in the context, and monitor instance IDs.
`e`	`enable`	Enables debugging. You must run this in order to do any debugging.
`d`	`disable`	Disables debugging. You must run this to disable debugging. If you do not disable debugging, the correlator runs more slowly and continues to stop when it hits breakpoints.
`boe`	`breakonerror enable`	Causes the debugger to pause if it encounters an error.
`boeoff`	`breakonerror disable`	Causes the debugger to continue processing if it encounters an error.
`ba`	`breakpoint add [--breakonce] --file filename --line linenumber \| [--breakonce] --owner ownername --action actionname --line linenumber`	Adds a breakpoint at the beginning of the specified line. If you do not specify `--breakonce`, the correlator always pauses at this point when debugging is enabled. You must specify the line number where you want the breakpoint. As usual, this is the absolute offset from the beginning of the file. You must specify either the name of the file that contains the breakpoint or the owner and action name that contains the breakpoint. When the owner is a monitor instance, specify `package_name.monitor_name` or just `monitor_name` if there is no package.
`bd`	`breakpoint delete --file filename --line linenumber \| --owner ownername --action actionname --line linenumber \| --breakpoint breakpointid`	Removes a breakpoint. Specify one of the following: - File name and line number. Owner name, action name and line number. When the owner is a monitor instance, specify `package_name.monitor_name` or just `monitor_name` if there is no package. Breakpoint ID. You can obtain a breakpoint ID by executing the `breakpoint list` command.
`bls`	`breakpoint list`	For each breakpoint in the correlator, this displays the following: - Breakpoint ID. Name of file that contains the breakpoint. Name of the action that contains the breakpoint. Name of the owner of the breakpoint. Number of the line that the breakpoint is on. The breakpoint owner is the name of the monitor that contains the breakpoint or the name of the event type definition that contains the breakpoint. If the breakpoint is in an event type definition, the definition must specify an action and processing must create a closure between an event instance and an action call. For information about closures, see Using action type variables.

Exit status

The engine_debug tool returns the following exit values:

Value	Description
`0`	Success. All requests were processed successfully.
`1`	Failure. The correlator could not parse the command line, or an exception occurred, such as losing a connection or trying to use a non-existent ID.

Obtaining online help for the command-line debugger

The command-line debugger provides online help. To obtain general information, enter the following:

engine_debug help

To get help for a particular command, specify that command after the help keyword.

For example, if you want to find out what the status command does, enter the following:

engine_debug help status

Or to find out which options you can specify with the breakpoint add command, enter the following:

engine_debug help breakpoint add

Enabling and disabling debugging in the correlator

To use the debugger, you must enable debugging in the correlator. To enable debugging locally on the default port, enter the following:

engine_debug enable

When you are done debugging, you should disable debugging in the correlator. If you do not, the correlator runs more slowly and continues to pause when it hits a breakpoint. To disable debugging in the local correlator on the default port, enter the following:

engine_debug disable

You can also enable and disable the debugger in a remote correlator by specifying the host name and the port number. For example:

engine_debug enable --host foo.bar.com --port 1234

engine_debug disable --host foo.bar.com --port 1234

Working with breakpoints using the command-line debugger

You can use the command-line debugger to add, list and remove breakpoints.

Adding breakpoints

There are two ways to add a breakpoint. If you know the EPL file name and the line number, you can enter something like the following:

engine_debug breakpoint add --file filename.mon --line 27

When you specify a file name, you must specify the exact path you specified when you injected the monitor. For example, suppose you ran the following:

engine_inject foo.mon

You can then specify “foo.mon” for the file name. Now suppose you ran this:

engine_inject /foo/bar/baz.mon

You must then specify “/foo/bar/baz.mon” for the file name.

If you prefer to use the monitor and action name, along with the line number, enter something like this:

engine_debug breakpoint add --monitor package.monitor --action actionName
   --line 27

The debugger output indicates the line number where it added the breakpoint. In some cases, the debugger does not set the breakpoint on the line you specified, for example, when a statement runs over multiple lines.

Listing breakpoints

To obtain a list of the breakpoints currently set in the correlator, enter the following:

engine_debug breakpoint list

Removing breakpoints

To remove a breakpoint by specifying the file name and the line number, enter something like the following:

engine_debug breakpoint delete --file filename.mon --line 27

To use the monitor name to remove a breakpoint, enter something like this:

engine_debug breakpoint delete --monitor package.monitor --action actionName
   --line 27

To delete a breakpoint by using the breakpoint ID that appears in the breakpoint list returned by the debugger, enter something like this:

engine_debug breakpoint delete --breakpoint 1

Controlling execution with the command-line debugger

When the correlator stops at a breakpoint, you can use the debugger to step over the next line:

engine_debug stepover

However, you most likely want to step over the line, confirm that the correlator stopped, and learn about the current state of the debugger. You can do this by entering multiple commands in one line. For example:

engine_debug stepover wait --timeout 10 status

This is the equivalent of the following three commands:

engine_debug stepover — Causes the debugger to step over one line of EPL.
engine_debug wait --timeout 10 — Causes the debugger to pause until either a breakpoint is hit, or ten seconds pass.
engine_debug status — Displays the debugger’s current status.

Following are more examples of entering multiple commands in one line.

engine_debug stepinto wait --timeout 10 status

engine_debug stepout wait --timeout 10 status

To instruct the correlator to continue executing EPL code, run the following command:

engine_debug run

You use the engine_debug run command regardless of how the correlator was stopped — a breakpoint was reached, a step operation, a wait command.

To stop the correlator, enter the following command:

engine_debug stop

The wait command

The wait command connects to the correlator to determine if the correlator has suspended processing. If the correlator is in suspend mode, the wait command returns immediately and debugging continues. If the correlator is not in suspend mode, the wait command remains connected to the correlator. The wait command returns when something else suspends the correlator or when the timeout is reached. Operations that can suspend the correlator include reaching a breakpoint, stepping into or over a line, or some other client explicitly stopping the correlator. If the wait command reaches the timeout, it suspends the correlator before it returns.

Stepping can take a variable amount of time. For example, suppose the debugger stops at the end of a listener and you execute a step command. The debugger is now outside the flow of execution until another event comes in. The time that the debugger has to wait for the step to finish is dependent upon when the next matching event arrives.

Command shortcuts for the command-line debugger

Putting multiple commands in the same command line can get verbose. For example, suppose you want to step out of an action on a remote machine. You would need to enter something like this:

engine_debug stepout --host foo.bar.com --port 1234 wait --timeout 10
   --host foo.bar.com --port 1234 status --host foo.bar.com --port 1234

The command-line debugger provides easier ways to invoke this.

Any arguments that you specify before the first debugging command apply to the entire command line.
All individual commands and their arguments have abbreviations.

For example, the following command does the same thing as the previous verbose command:

engine_debug -h foo.bar.com -p 1234 sot w -to 10 p

The following table lists the abbreviations you can use for command arguments. For abbreviations of commands, see Debug commands.

Command	Abbreviation
`--action`	`-a`
`--breakonce`	`-bo`
`--breakpoint`	`-bp`
`--context`	`-c`
`--file`	`-f`
`--frame`	`-fm`
`--host`	`-n`
`--instance`	`-mt`
`--line`	`-l`
`--owner`	`-o`
`--port`	`-p`
`--raw`	`-R`
`--timeout`	`-to`
`--utf8`	`-u`
`--variable`	`-v`
`--verbose`	`-V`

Examining the stack with the command-line debugger

When the correlator stops at a breakpoint, you can display the stack with the following command:

engine_debug stack

The results of this command show the number of the frame that contains each variable. In the following example, the frame number is the number before the right parenthesis:

0 )
        somedir/test.mon:35
        foo.baz.test.runtest[setupctx(2)/foo.baz.test(3)]
1 )
        somedir/test.mon:19
        foo.baz.test.::listenerAction::[setupctx(2)/foo.baz.test(3)]

You can use these frame numbers (frame IDs) as arguments to the engine_debug inspect command.

To see just the contents of the top frame, run this command:

engine_debug stack --frame 0

Displaying variables with the command-line debugger

To list all variables in the current stack frame, enter the following:

engine_debug inspect

To obtain the value for a variable in the current stack frame, enter the following:

engine_debug inspect -variable variableName

To obtain the value for a variable further down the stack, run the stack command to determine the frame number and then enter the following:

engine_debug inspect -variable variableName -frame frameid