The StreamBase Studio Trace Debugger perspective 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, 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 → . You then send data to the application. When you stop the application, you view the file's contents in the SB Trace Debugger perspective.
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:
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.
Click the Trace Debugger button in the Studio toolbar, or select → → .
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:
Send tuples to the application manually or with a feed simulation.
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.
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 thebutton, reopen the current file by clicking , and close the file and remove all trace display window tabs that you have created when tracing by clicking . 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 will automatically open when you stop the application.
Browse the currently open trace file using the Browse pane. Set the timestamp index slider to view contents of tuples emitted in the time frame it indicates. The default is the first tuple in the file.
Clickto 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 Matches tab of that pane.at the bottom of the pane, you see a list of the tuples that match your query in the
When you Click, 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.
Thebutton 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 theand buttons, respectively.
Click in 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 . When you select rows, the locations in your application they map to are highlighted, as shown below:
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 default temporary directory (normally
C:\Users\username\AppData\local\temp). However, you can
specify a location for trace files by selecting , clicking the
tab, enabling the button under Persistent Data Options and typing or browsing to a path naming the
If you are reviewing a trace from a prior session, to enable highlighting of operators, data constructs, and adapters as shown above, you need to associate the trace file with the EventFlow application that created it. To do that, click thebutton under the navigation buttons in the trace data display window and select the application that was traced from those in your workspace.
Trace files are created in pairs, with the data in a
.gz archive and schema information in a
.sbtrace-meta XML file. Trace file names take the form
The associated meta file name takes the form
Trace files persist until you manually delete them. As they can grow quite large for complex applications, especially when run at high data rates, you should monitor the contents of your trace file folder and delete files you no longer need.
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 run-time tracing to only include them. Do this by specifying a regular expression in the Advanced tab of the Trace Configurations dialog. Select , 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
BestBidsAsk.sbapp and in the field type
BestBids to trace only tuples that represent
bids, not asks. Click , 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 also restricts what tuples the Trace Debugger displays. When analyzing a trace file, you can view only those tuples that arrive at certain operators with a value that you specify. The matching is applied to all fields unless you restrict it by clicking the twist-downcontrols next to operator names in the Query pane and deselecting field names.
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, etc.