Trace Debugging in StreamBase Studio

The SB Trace Debugger perspective in StreamBase Studio provides a way to review and analyze runtime trace files generated while an application was running. You can load and analyze trace files any time after the application has stopped.

Trace debugging is a way to study an application's behavior offline by stepping through a trace file, line by line. The file contains rows of tuple values in the order they were processed, and shows you how they change, stream by stream. If your application is open in Studio, then when you step through a trace, the location of each line you select in the trace debugger is automatically highlighted in the associated EventFlow module.


Unlike regular debugging, which you do while running in Debug mode, enabling trace debugging generates a trace file of input, output, and intermediate tuples when you execute your application with RunTrace As. You then send data to the application. When you stop the application, you view the file's contents in the SB Trace Debugger perspective.

Creating a Trace File in Studio

You can generate trace files for this purpose in two ways:

  • Enable trace file generation for your application as described in Runtime Tracing and Creating Trace Files. When you run your application, either provide it with test data in a feed simulation, or run it with live data. When the application stops, switch to the SB Trace Debugger perspective and open the generated trace file.

  • Launch your application in Studio in Trace Debug mode.

Trace Debug mode is a third launch mode for running applications in Studio, in addition to Run and Debug modes. To run In Trace mode:

  1. Start with your application's EventFlow, StreamSQL, or Deployment File Editor open, with the application typechecked and free of errors. It is best to have a feed simulation prepared and ready to run.

  2. Click the Trace Debugger button in the Studio toolbar, or select RunTrace AsStreamBase Application.

  3. Studio runs the application normally and automatically starts recording a trace file for the main application in the default container. The status button in the lower left corner of the Studio window shows a message like the following:

  4. Send tuples to the application manually or with a feed simulation.

  5. When you stop the application, Studio automatically switches to the SB Trace Debugger perspective, with the newly-recorded trace file already loaded. You can now use this perspective to follow the progress of a single tuple through your application.

You can edit and save Trace Debugger launch configurations in the same way as Run and Debug launch configurations. For more information, see Editing Launch Configurations.

Analyzing Trace Files

When you open the SB Trace Debugger perspective, you see its Query View with your most recent trace file preloaded. You can select different trace files using the Browse button, reopen the current file by clicking Refresh, or close the file and remove all trace display window tabs that you have created when tracing by clicking Reset Session. The Query View is shown in the following illustration:

The Query view lets you:

  • Navigate to and open a trace file using the Trace File pane. If you have just performed a trace, its file automatically opens when you stop the application.

  • Browse the currently open trace file using the Browse pane. Set the Time timestamp index slider to view the contents of tuples emitted in the time frame indicated. The default is the first tuple in the file.

    Click Open Tuple Trace to open a view in which you can trace the path of that tuple through the application.

  • Use the Search pane to search the trace file for a particular field value. The value you specify is a string, not an expression, and it can occur in any tuple field. (The trace file is a CSV file that does not specify data types, so there is no typechecking.)

    When you select Run Query at the bottom of the pane, you see a list of the tuples that match your query in the Matches tab of that pane.

When you Click Open Tuple Trace, you see a representation of tuples for the time frame in the trace results window as a grid of color-coded values. Here is an example of tuples displayed in that window.

The Color Legend button on the top right of the display panel describes the color coding for the tuples:

Step through input tuples in the file backward and forward with the Previous Tuple and Next Tuple buttons, respectively.

Click a row of tuples to select it, or Shift+click to select a range of rows. To copy the selection to the clipboard, right-click and select Copy Selected Rows. When you select rows, the locations that they map to in your application are highlighted, as shown below:

Further Details about Trace Debugging

Unless you have changed configuration settings (as described in Setting Up for Runtime Tracing), StreamBase Studio is pre-configured for trace debugging. The default location for your trace files is your system's default temporary directory (normally C:\Users\username\AppData\local\temp on Windows or /tmp on Linux and UNIX). However, you can specify a location for trace files by selecting Run -> Trace Configurations, clicking the Advanced tab, enabling the Specified button under Persistent Data Options and typing or browsing to a path naming the desired location.

Associating a Trace File with a StreamBase Application

If you are reviewing a trace from a prior session, to enable highlighting of operators, data constructs, and adapters as shown above, you must associate the trace file with the EventFlow application that created it. To do that, click the Associate button under the navigation buttons in the trace data display window and select the application that was traced from those in your workspace.

Managing Trace Files

Trace files are created in pairs, with the data in a .gz archive and schema information in an .sbtrace-meta XML file. Trace file names take the form application-name-timestampcontainer-name.sbtrace.gz. The associated meta file name uses the same basename with the .sbtrace-meta extension.

Trace files persist until you manually delete them. Because they can grow quite large for complex applications, especially when run at high data rates, be sure to monitor the contents of your trace file folder and delete files you no longer need.

Restricting the Scope of Traces

You can limit the size of trace files and save time when analyzing them by restricting their scope. If you are only interested in debugging certain operators and streams, you can restrict runtime tracing to only include them. Do this by specifying a regular expression in the Advanced tab of the Trace Configurations dialog. Select Filter trace data using this regular expression when tracing, and enter the expression in the text box next to it. Use a regular expression to be parsed by java.util.regex.Pattern.

For example, if you are interested only in tuples that end up at one of several output streams, you can insert the name of that operator in the text field labeled Filter trace data using this regular expression when tracing. Open the StreamBase sample BestBidsAsk.sbapp and in the Filter trace data using this regular expression when tracing field, enter BestBids to trace only tuples that represent bids, not asks. Click Trace, and run with the NYSE.sbfs feed simulation. When you stop BestBidsAsks, the SB Trace Debugger perspective displays only tuples arriving at the BestBids output stream.

The Search pane in a Query view can also restrict what tuples the Trace Debugger displays. When analyzing a trace file, you can narrow the view to only those tuples that arrive at certain operators with a value that you specify. The value match is applied to all fields unless you limit the match to specific fields; to do this, click the arrow control next to the operator names of interest in the Query pane, and clear the check box for the fields you want to exclude.

Search terms are simple strings. Matching values may include substrings containing the search term. Thus, searching for 4.0 will also find values of 14.0, 4.05, and so on.