Contents
When enabled, runtime tracing writes tuple trace information to StreamBase Server's console or to a trace file, one file per container. If any component or module in your application uses concurrency features, then a separate trace file is created for each separate parallel region. (See Execution Order and Concurrency for more on concurrency.)
The default trace information is a single timestamped line per tuple. Each tuple is shown as received at each operator and stream in the application. Trace files can grow quite large very quickly, so runtime tracing is best used only for short bursts, for debugging only, to follow a tuple's progress through an application.
You can limit the number of operators and streams that are subject to tracing by using a regular expression to narrow the list of the components of interest.
Tracing does not occur unless you enable tracing by setting streambase.codegen.trace-tuples to true in a HOCON configuration
file of type c.t.e.streambase.c.sbengine, in the StreamBaseEngine root object. For example:
name = "sbengine"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.sbengine"
configuration = {
StreamBaseEngine = {
systemProperties =
{
"streambase.codegen.trace-tuples" = "true"
}
}
}
You can manage settings for your trace session as described in Configuring Runtime Tracing
Trace files have the extension .sbtrace, or
.sbtrace.gz for compressed files. Trace files are
stored with UTF-8 encoding, which preserves any Unicode characters in tuple fields in
the trace file.
Runtime tracing is similar to, but not the same as using sbc dequeue to dequeue tuples from any stream in your application, including intermediate streams, if enabled (see Intermediate Stream Dequeuing). The following table shows the differences between runtime tracing and dequeuing.
| Feature | Standard Dequeuing | Runtime Tracing |
|---|---|---|
| See tuple output from ... | All explicit streams by default, and all intermediate streams if enabled. | All operators and streams (optionally limited by regular expression selection). |
| Timestamp shown for each tuple | No | Yes |
| Save output to a file or console | Must redirect console output or use an output adapter. | Specify with a runtime option. |
| Starts with StreamBase Server | No. It takes time to start the Server, then start a dequeuing client. The first few tuples can be missed. | Yes. Even the first few tuples are captured. |
| Can see tuple output in StreamBase Studio | Yes. | Yes. |
Configure runtime tracing with one of three methods:
-
Specify configuration settings in a HOCON configuration file of the type c.t.e.streambase.c.sbengine type, in the EventFlowDeployment root object. See the
modules>traceproperties, as described in the following table. -
Use the epadmin add container command at runtime with its
--trace*options. -
Use the epadmin modify container command at runtime with its --trace true and --trace false subcommands, and its
--trace*options.
Check the Introduction to Runtime Tracing to enable
tracing before the application starts. You can disable tracing at runtime with
epadmin [sn|ad] modify container .
In that case, re-enable tracing with --name containerName --trace falseepadmin [sn|ad]
modify container . As soon as you disable or stop tracing, all trace files
are closed.
--name containerName
--trace true
All three methods invoke the same options, described in the following table:
| HOCON property | epadmin option | Default | Description |
|---|---|---|---|
"matchOperatorAndStreamRegexp" = "pattern"
|
--tracestreampattern="pattern"
|
none |
Specify a regular expression If not specified, tracing is active for all operators and streams in the application. |
fileBase="basename"
|
--tracefilebase="basename"
|
none |
By default, trace output is written to StreamBase Server's console. To
redirect trace output to a file, specify
There is one trace file generated per module, including one trace file for
each parallel region in a module. Specify a string to serve as the
|
| overwrite="true" | --traceoverwrite | false |
For the
Setting to |
| compress="true" | --tracecompress | false |
For the
Set to |
| buffered="false" |
--tracebuffered=true
--tracebuffered=false |
true |
When set to false, the output trace file is
flushed on every trace line. This slows down performance considerably, but
makes it easier to use tracing as part of debugging a live application. When
set to true (the default), tracing output is
buffered before the trace file is written, to minimize tracing's drag on
performance.
|
Trace files consist of one header line (shown below on two lines for publication
clarity), plus one trace line per tuple received at each specified operator and
stream. The following example shows the start of a trace file for the Best Bids and
Asks sample included in StreamBase, running in the default container named
default:
# ms since epoch, tupleid, operator/streamname, tuple-data - \ trace started: 2010-11-04 16:09:22.200-0400 - 1288901362200ms 1288901370904,1,default.NYSE_Feed,33409,NLY,14.0,0,16.0,0,13033 1288901370906,1,default.out:Update_Bids_and_Asks_1,33409,NLY,14.0,16.0,14.0,16.0 1288901370906,1,default.out:IsNewBestAsk_1,33409,NLY,14.0,16.0,14.0,16.0 1288901370906,1,default.BestAsks,33409,NLY,16.0 1288901370906,1,default.out:IsNewBestBid_1,33409,NLY,14.0,16.0,14.0,16.0 1288901370906,1,default.BestBids,33409,NLY,14.0 1288901370906,2,default.NYSE_Feed,33620,NCC,28.5,0,30.5,0,13249 1288901370906,2,default.out:Update_Bids_and_Asks_1,33620,NCC,28.5,30.5,28.5,30.5 1288901370906,2,default.out:IsNewBestAsk_1,33620,NCC,28.5,30.5,28.5,30.5 ...
Trace lines consist of at least four fields, described in the following table:
| Field | Description |
|---|---|
| 1 | Timestamp in milliseconds representing the interval of time since the epoch. |
| 2 | Tuple ID. |
| 3 | Fully qualified name of the operator or stream output port. |
4 through n
|
The comma-separated fields of the tuple as it exits the port described in field 3. |