Using the Visual Debugger

Contents

Introduction
Visual Debugger Terminology
Breakpoint Lifecycle
Running Applications in Debug Mode
Using Visual Debugger Features

Introduction

The StreamBase Studio Visual Debugger allows you to see what is going on inside your StreamBase application by inspecting the incremental processing of tuple data. You can suspend a StreamBase application at specified breakpoints, display tuple contents after every operator, and step into and out of modules. If you have used program debuggers before, the Visual Debugger's commands and options will be familiar.

The Visual Debugger is only available for EventFlow applications, not StreamSQL. It is an interactive inspection facility and is not for general monitoring or use as a trace debugger for diagnosing server behavior. It is only available within a StreamBase Studio session and is not accessible through the StreamBase Client API.

The Visual Debugger is based on the Eclipse Debug Framework (EDF), and is accessed through the SB Test/Debug perspective. Studio re-uses the Eclipse EDF's Debug, Variables, and Breakpoint views. Because the Visual Debugger inherits from a Java code debugger, many of its features do not apply to EventFlow debugging. You can learn about the basic Visual Debugger features and operations in the Java Development User Guide that's included in the Studio help system. Look for Concepts → Debugger in that guide.

Visual Debugger Terminology

Breakpoint: A marker that pauses a thread of the program when execution reaches that point.
Execution point: The paused location in the execution flow of a thread, just before the next statement to be executed.
Watchpoint: A setting that stops the running program when a variable is written or read.
Launch: A run configuration loaded into the Debug view that shows showing the VM and stack frame of suspended processes.
Stack Frame: The list of operators visited by a tuple during its lifetime.
Process: A single thread representing an independent executable portion of a running application.
VM: The Java Virtual Machine interpreting the StreamBase application.

Breakpoint Lifecycle

For EventFlow applications, breakpoints are set on arcs. The breakpoint lifecycle begins when you select arcs in the EventFlow editor from which to initiate inspection and control of the application. An active breakpoint pauses the process or VM that encounters it and meets its filter criteria. When paused, the state of the application can be inspected. A breakpoint can be created, modified, disabled, or removed and those changes will take effect when the application is permitted to continue execution.

To create or remove a breakpoint, right-click an arc in the EventFlow editor and choose Toggle Breakpoint.

Breakpoints can be created and modified at any time during the editing or debugging session, even while the application is running. However, most useful tasks are done when the application is suspended.

Most applications consist of multiple threads that take input from continuously running input sources. Pausing a single process or thread does not pause processes running outside the VM, so input buffers can fill while parts of an application are paused. Take care to control input data while debugging in order to minimize the impact of pausing the main application.

Breakpoints are saved with the project and can be exported for import into other projects.

Viewing Tuple Contents

A tuple's value is displayed in the Variables View any time the EventFlow application is suspended and the execution point is at an operator.

Start the application in debug mode and switch to the Debug View. Click the Suspend button in the toolbar of the Debug View to pause the execution of the application. If the application is waiting for data, supply a tuple on any input stream. When the process suspends at that input stream, the next tuple available on that stream appears in the Variables View. The tuple appears as the top node in a hierarchical list. Expand the list to see the individual field names, values, and types. Long values can be seen in the Detail pane with wrap turned on.

Tip

Place the Variables View, Debug View, and Application Output View in separate portions of the Studio screen so you can see the contents of all tabs at the same time. The step commands are in the Debug View, but the tuple values are visible in the Variables View.

Conditionally Suspending the Application

Specifying a Hit Count value to disable breakpoints during a single session until a specified number of tuples have visited that location in the EventFlow.

Suspension Policy

The debugger works in either of two modes based on suspension policy, either to suspend the thread on a breakpoint or suspend the VM on a breakpoint. If the VM is suspended, support services like Heartbeat are also suppressed. If only the thread is suspended, all other threads continue. This can introduce tuple ordering differences in applications with multiple parallel concurrent operators and modules, which would not occur during normal operation.

Running Applications in Debug Mode

To use the Visual Debugger features, run your application in debug mode as described in these topics:

Using Visual Debugger Features

This section introduces the Visual Debugger views and commands. There are four views used by the Visual Debugger:

EventFlow editor view: Use this view to create and remove breakpoints, and to follow the flow of execution as it passes through your application.
Debug view: Shows processes in the running application. Use the toolbar buttons of this view to pause and resume your running application, and to step into or step over modules.
Breakpoints view: Use this view to edit breakpoint properties.
Variables view: Shows tuple contents, parameters, and dynamic variable content as execution passes through your application. You can use this view to create watchpoints.

During a debugging session, you suspend individual threads of your application using the Debug view, set breakpoints in the EventFlow editor, and select process stack frames in the Debug View to inspect in the Variables View.

EventFlow Editor

The EventFlow editor shows the flow of the application and marks any arcs containing breakpoints with a symbol. Select an arc and right-click to access the Toggle Breakpoint, Disable Breakpoint, and Enable Breakpoint commands from the context menu.

When the application is suspended, selected stack frame items in the Debug View are shown with a blue background in the EventFlow editor.

Debug View

The Debug View allows you to manage the debugging or running of a program in the workbench. For a given launch configuration, the Debug View shows a hierarchical list of each VM and process. Each thread that comprises a StreamBase application appears as a node in the tree. Under each suspended EventFlow thread, the Debug View displays the operator stack. Monitors, System Threads, Qualified Names, and Thread Groups are optionally shown.

To compare with debugging a Java application, in place of Java statements, stack frame elements represent StreamBase operators. For the purpose of controlling program execution, an operator is treated as a single statement, and modules are treated as functions. Not all commands that are available when debugging Java code are available when debugging EventFlow applications due to the high-level abstractions required for EventFlow processing.

The commands described in the next sections are available from the toolbar and the right-click context menu.

Commands for Launch Management

Resume: Allow a process to return to the running state.
Suspend: Remove a process from the running state for inspection without unloading its threads.
Terminate: Stop a process and unload its threads. A terminated process cannot be resumed. The SB Test/Debug perspective closes and the previous perspective is restored.
Disconnect: Permit a remote launch and its processes to run without further interaction with debugging commands.
Terminal All: For EventFlow debugging, equivalent to Terminate.
Terminate and Remove: For EventFlow debugging, equivalent to Terminate.
Remove all Terminated Launches: Not meaningful for EventFlow debugging.
Relaunch: Not meaningful for EventFlow debugging.

Commands for Thread Management

Step Into: Enters a module or executes the next operator in the current stream. The application suspends at the next available execution point, which can be inside a module in a separate EventFlow file.
Step Over: Executes the entire function of a module or execute the next operator in the current stream. The application suspends at the next available execution point in the current EventFlow file.
Step Return: Executes the entire function of the current module or EventFlow application until control passes to the calling EventFlow application.
Drop to Frame: Not available for EventFlow debugging. Instead, inspect historical tuple contents in the Variables View by selecting earlier operators in the process stack in the Debug View.
Use Step Filters: Not meaningful for EventFlow debugging.

Breakpoints View

The Breakpoints View lists the breakpoints you currently have set in your workspace. You can double-click a breakpoint to display its location in the editor (if applicable). You can enable or disable breakpoints, delete them, add new ones, group them by working set, or set hit counts. This view also controls whether only a thread is suspended, or the entire VM (additional control and inspection is available if the entire VM is suspended).

The commands described in the next sections are available from the toolbar and the right-click context menu.

Commands for Breakpoint Management

Remove Selected Breakpoints: Selected breakpoints are removed.
Remove All Breakpoints: All breakpoints shown are removed.
Show Breakpoints Supported by Selected Target: Filters the display to show only the breakpoints which affect the current Launch.
Go to File for Breakpoint: Opens the EventFlow application in the EventFlow editor in which the selected breakpoint is defined.
Skip All Breakpoints: Permits the running application to ignore all breakpoints.
Suspend VM: Suspends the VM containing the breakpoint.
Suspend Thread: Suspends the thread containing the breakpoint.
Hit Count: Sets the number of tuples that must visit the breakpoint before it suspends the running application.
Exit: Sets the breakpoint to suspend after the operator executes.
Entry: Sets the breakpoint to suspend before the operator executes.
Enable: Permits this breakpoint to suspend the VM or thread.
Disable: Prevent this breakpoint from suspending the VM or thread.
Remove: Removes this breakpoint from the EventFlow editor.
Remove all: Removes all breakpoints from the EventFlow editor.
Select All: Select all breakpoints.
Copy: Copy the text description of a breakpoint into the system clipboard.
Paste: Paste a breakpoint description into the breakpoint view (if an appropriate target is available).
Export Breakpoints: Save the breakpoints to an external file.
Import Breakpoints: Read defined breakpoints from a file into the breakpoint view.
Breakpoint Properties: Edit the behavior of a breakpoint (Enabled, Hit Count, Suspend on Entry or Exit, Suspend Thread or VM).
Filtering: Not meaningful for EventFlow debugging.

Commands for Breakpoint View Management

Expand All: Show all breakpoints in the workspace.
Collapse All: Show only the top level hierarchical nodes.
Link with Debug View: When an application suspends on a breakpoint in the Debug View, the associated breakpoint will be highlighted in the Breakpoints View.
Add Java Exception Breakpoint: Not meaningful for EventFlow debugging.
Group By: Specifies nested groupings for the Breakpoints view.
Working Sets: Define a specific set of breakpoints to appear in the view.
Select Default Working Set: Select a set of breakpoints to appear in the view.
Deselect Default Working Set: Reset the view so that no working set is selected.
Show Qualified Names: Not meaningful for EventFlow debugging.

Variables View

The Variables View displays information about the tuple associated with the operator currently selected in the Debug View stack frame. A tuple can have more detailed information displayed in the detail pane. The tuple appears as the top node in a hierarchical list. Expand the list to see the individual field names, values, and types. Long values can be seen in the detail pane with wrap enabled.

The commands described in the next section are available from the toolbar and the right-click context menu.

Commands for Variables View Management

Show Type Names: Not meaningful for EventFlow debugging.
Show Logical Structure: Not meaningful for EventFlow debugging.
Collapse All: Show only the top node(s).
Layout > Vertical View Orientation: Place the list above the detail pane in the view.
Layout > Horizontal View Orientation: Place the list to the left of the detail pane in the view.
Layout > Variables View Only: Hide the detail pane.
Layout > Show Columns: Toggle whether columns appear, providing additional information.
Layout > Select Columns: Optionally show additional information including Name, Declared Type, Value, Actual Type.
Java: Not meaningful for EventFlow debugging.
Select All: Highlights all rows in the hierarchical list.
Copy Variables: Copy the text description of selected fields to the system clipboard.
Find: Select fields by name.
Change Value: Not meaningful for EventFlow debugging.
All References: Not meaningful for EventFlow debugging.
All Instances: Not meaningful for EventFlow debugging.
New Detail Formatter: Not meaningful for EventFlow debugging.
Open Declared Type: Not meaningful for EventFlow debugging.
Open Declared Type Hierarchy: Not meaningful for EventFlow debugging.
Create Watch Expression: Not meaningful for EventFlow debugging.
Inspect: Add the selected tuple to the Expressions View. Note that Watch Expressions are not supported for StreamBase data types.