Tutorial for the Command-Line Debugger (Deprecated)

Here is a brief description of the sbdbtutorial sample application we will be debugging.

We will now start the server and load the sbdbtutorial.sbapp application in a way that enables us to use sbdb with that application.

For a summary of the sbdb commands, see the sbdb reference topic.

Since StreamBase Server starts up in running mode, pause it before proceeding.

In the window where sbdb is running, type: pause.

sbdb> pause

Pause: OK
sbdb>

sbdb allows debugging an application regardless of whether data is streaming into the server. For this tutorial, we will send a small amount of data from a file and step through the processing of those tuples.

Open a third terminal window or StreamBase Command Prompt and send the contents of input.csv to the application by entering:

sbc enqueue InputStream < input.csv

We are now ready to learn how to use sbdb. Return to the window running sbdb.

sbdb> 

Status: Server is paused
0 breakpoints set
Thread 'main' is paused in i0:SourceTagger on (myint=2300)
sbdb>

This section introduces the sbdb commands.

The status command provides information about the server. Let's break down the status lines in the preceding example:

The list commands allow us to find out more about the loaded application. Let's try three of them now:

We will look at the list breakpoints command in more detail later in this tutorial.

The step command allows us to control the execution of operators and observe the flow of data within an application. The step command instructs the processing engine to execute the next operator in the current thread. The operator receives tuples on its input port or ports, and outputs any results. The number of tuples it will consume is not specified. Let's use the step command to trace the execution of this application:

The commands we have used up to this point allowed very fine, manual control over the processing of tuples. This may not be ideal if you wish to process a large number of tuples before inspecting StreamBase Server, or if you are operating on streaming input data that you do not know the contents of in advance. Breakpoints are a way of letting StreamBase Server pause for you when a certain condition on any input port is met. Let's work through an example.

The break command is used to add a breakpoint on some input port, by placing a condition that is evaluated against every tuple entering this port. If the condition ever becomes true, the processing engine pauses itself, and sbdb sessions are notified of this event. Let's see an example of this in action.

Imagine that the value of myint should never exceed 8000, even after the doubling operation done by the MapDouble operator. To check for this condition, we will add a breakpoint on both input ports of the Union operator, as follows:

sbdb> break i0:default.Union myint>8000

Breakpoint: OK; Breakpoint 1 at i0:default.Union added.

sbdb> break i1:default.Union myint>8000

Breakpoint: OK; Breakpoint 2 at i0:default.Union added.
sbdb> 

We can confirm the breakpoints we added by using the list breakpoints command, which lists the breakpoint id, the break condition, and the location:

sbdb> list breakpoints

List: OK; 
[1]: myint>8000 on i0:default.Union
[2]: myint>8000 on i1:default.Union
sbdb>

Now we will unpause the server, allowing tuples to be processed until the moment one of our breakpoints is triggered. The trigger should be a tuple, entering either input port of the Union operator, whose myint field has a value greater than 8,000. To unpause the server, enter the following command. (You may have to restart the sbc enqueue command in another window.)

sbdb> continue

Continue: OK; 
sbdb>
Breakpoint 2 hit at i1:default.Union (myint=8010, source="test"); server is pausing
(Ctrl+L to redisplay your input line)
sbdb> 

This message indicates where a breakpoint was hit.

Although this message was displayed in response to your continue command, breakpoints can be triggered at any time during exectution. For UNIX, if a message is displayed while you were typing on the Debug command line, you can press Ctrl-L to redisplay the sbdb> prompt and any text you might have been typing when you were interrupted. For Windows, just type on the unprompted line that follows the last output.

Now run the status command.

sbdb> status

Status: Server paused
2 breakpoints set
Thread 'main' is paused in i1:default.Union on breakpoint 2 on (myint=8010, source="test")
sbdb> 

The server pauses right after the tuple triggered the breakpoint, and we can see the triggering tuple at the Union operator's second input port.

We can see that a tuple was output from the MapDouble operator with a value for myint of 8010, which triggered the breakpoint. Breakpoints can be set to handle a condition, or to pause the server as soon as any tuple enters some input port. (See help break for the exact syntax.)