sbprofile
StreamBase Profiler — Runs the StreamBase profiler to produce formatted statistics about operators and queues in a running server.
DESCRIPTION
Use sbprofile to produce formatted statistical profile information about operators, queues, threads, and system information in a given
run of StreamBase Server. sbprofile reads the raw system.statv2
statistics stream from a live server process (-u
or -p
options), which can be compressed with gzip. When calculating operator description information (-d
or -D
options), sbprofile also examines the currently running application on the server.
The sbprofile command does not analyze and draw conclusions from the system statistics. Its purpose is to extract useful information from the system statistics stream and format it for manual or automated inspection. See Profiling for examples of output and for an overall discussion of StreamBase profiling.
By default, sbprofile with no arguments connects to the default server URI, sb://localhost:10000
, and prints to stdout
a set of CSV formatted statistics lines, one line for each active operator, queue, and thread, plus a line of system information.
sbprofile prints one set of statistics for every system.statv2
snapshot interval, which is once per second by default. You can change the snapshot interval using the <period-ms>
parameter of the <sbmonitor>
element in the server configuration file. (See <sbmonitor> for details.) The command extracts and formats statistics until it is stopped with Ctrl+C or until the server shuts down.
Note
The profiling system shows meaningful statistics only for operators and queues that have run for a while. It is common to have StreamBase applications with operators that use no measurable amount of CPU time when the application has not run very long or has not run with much data. For low latency applications running on fast CPUs, it could take hundreds of thousands of tuples to register statistics greater than zero.
Use only one of the -u
or -p
options. You can specify connecting to a live server at a different StreamBase URI than the default (-u
), or to the localhost server on a non-default port (-p
).
Use the output options (-o
, -b
, and -c
) to redirect the formatted output to a file (or to a bzip2 or gzip compressed file).
Do not confuse sbprofile's input and output files. If used, the input file is a collection of raw statistics emitted from a server's system.statv2
stream, optionally compressed with gzip by an administrator. If specified, the output file is a formatted CSV or HTML file,
extracted from the input stream, optionally compressed with gzip by the sbprofile -c
option or with bzip by the -b
option. The output of sbprofile cannot be used as the input of another sbprofile command.
In the CSV output format, each emitted line begins with a field containing a single letter that distinguishes the output type. The values in the first field are one of the following:
O for operator statistics lines. |
D for operator description lines. |
Q for queue statistics lines. |
T for thread statistics lines. |
S for system information lines. |
G for JVM garbage collection statistic lines. |
s for stream statistics lines, for input or output streams. |
For the meanings of the other fields in each output line type, see the field tables in the Meanings of the Profiling Statistics Collected section of the Profiling page of the Administration Guide.
Note
When a StreamBase application starts, the JVM associated with StreamBase Server interprets the bytecode at the start of execution, compiles it into native CPU instructions, and then optimizes it as the application is run. Thus, when profiling, statistics gathered at the start of the run do not reflect the optimization timing that will be automatically applied as the application continues to run. Therefore, the longer the application runs, the more accurate the profile.
OPTIONS
You must specify one of -u
, -p
, or -s
(or specify -h
, which overrides these three options).
-u
sburi
-
Specifies the URI of the StreamBase Server instance to communicate with. See the sburi page of the Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion of the URI format and its shortcuts. The URI can also be set using the
STREAMBASE_SERVER
environment variable. If neither-u
,-p
, nor-s
is specified, the command proceeds with standard defaults as if you entered-u sb://localhost:10000
. -p
TCP-port
-
Specifies the port number on
localhost
for the StreamBase Server instance to communicate with. This is a shortcut alternative to specifying the full URI with-u
in cases where the server is running onlocalhost
on a port other than the default 10000.Note
The
-p
option is not supported for applications that have StreamBase authentication enabled (because there is no way to specify a username and password) or in conjunction with the multiple URI syntax. -b
filename
,--bzip2-outfile
filename
-
Specifies the path to a filename to contain the formatted output of the command, which will be compressed with bzip2. The
.bz2
filename extension is automatically appended to the filename you specify. Profile data is compressed in line and written to the target file in that form. Since profile output files have a regular format, bzip2 compression provides about half the file size of gzip compression. See the--roll-size
option for more information. -c
filename
,--compressed-outfile
filename
-
Specifies the path to a filename to contain the formatted output of the command, which will be compressed with gzip. The
.gz
filename extension is automatically appended to the filename you specify. Profile data is compressed in line and written to the target file in that form. See the--roll-size
option for more information. --client-info
client-info
-
Emit the client connection information provided in the
client-info
argument every few monitor cycles. -d
,--description
-
For each operator, emits its type once.
-D
,--properties
-
For each operator, emits any operator properties.
-o
filename
,--outfile
filename
-
Specifies the path to a filename to contain the CSV or HTML formatted output of the command. The default is to write to
stdout
. --roll-size
M
-
When
-o
,-b
, or-c
is used to write an output file, close the file when it reaches approximatelyM
megabytes and start writing to a new output file. The valueM
is approximate, as file sizes can vary considerably depending on the selected output options:-
With the
-o
option, final file size is can be slightly larger than specified. The extra amount is the size of the longest profile output line -1. -
With the
-b
or-c
compression options, final file size will be much smaller then specified (a factor of 10 is not uncommon), depending on its data content and which method is used for compression.
-
--roll-time
T
[M | H | D]-
When
-o
or-c
is used to write an output file, close the file whenT
time units have elapsed and start writing to a new output file. The time units are expressed as M for minutes, H for hours, and D for days, with H the default. -z
,--printZeroOperators
-
Include all operators, even those that have accumulated zero processing time. Include all queues, even those that have never had a size greater then 0. Include all threads, even those that have never had CPU time charged to them.
-h
,--help
-
Displays usage text.
-J
jvm-option
-
Specifies a system property setting or other JVM argument to be passed to the JVM that runs this sbprofile command. Use this option to specify temporary settings that affect only the current invocation of sbprofile. You must specify multiple
-J
options to specify multiple JVM arguments.There must be no space after the
-J
. For example, specify-J-Xmx2G
. Use the full option syntax forjvm-option
that you would use at the Java command line, including the initial hyphen. For example, specify-J-Dstreambase.log-level=2
to increase the log level for this invocation of sbprofile.Your
jvm-option
argument might require surrounding quotes, depending on the characters it contains and the shell you are using. However, do not use quotes to escape the spaces between separate JVM arguments; instead use separate-J
options. For example:-J-Xms512M -J-Xmx2G
ENVIRONMENT
STREAMBASE_SERVER
-
Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default StreamBase URI for StreamBase commands that take the
-u
option. If set, commands use the URI in this variable, overriding their built-in default URI, which issb://localhost:10000.
If this variable is set, you must use the-u
option to communicate with any server other than the one specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.