collector(1)collector(1)NAME
collector - subcommands of dbx used for performance data collection
SYNOPSIS
dbx
DESCRIPTION
The term collector is used to describe the data collection features in
dbx and the runtime support for those features in libcollector.so.
The dbx collector does not work for applications written in the
Java(TM) programming language; it can collect data for the Java virtual
machine, but the Java-specific functionality does not work from dbx.
(The terms "Java virtual machine" and "JVM" mean a virtual machine for
the Java(TM) platform.)
The data collected is described in the collect(1) man page. The col‐
lect command can collect data without using dbx.
DBX COMMANDS
The commands accepted by dbx to support performance data collection are
as follows.
collector { enable | disable }
Enable or disable data collection.
If no process is active, control whether or not an experiment is
collected when a process starts. If the mode is disable, do not
collect performance data. If the mode is enable, collect data
for all subsequent runs.
If a process is running, but no experiment is being collected,
and an enable command is received, start an experiment on the
running process. If a disable is given, but no experiment is
being collected, ignore the command with a warning.
If a process is running, an experiment is being collected, and a
disable command is received, terminate the experiment. If enable
is given, ignore the command with a warning.
If an experiment is terminated, but the process is left running
and an enable command is received, start a new experiment.
collector pause
Temporarily stop recording data during an experiment. Ignore
the command with no warning if recording of data is already
paused. Ignore the command with a warning if no experiment is
running.
collector resume
Resume recording data during an experiment. Ignore the command
with no warning if recording of data is not paused. Ignore the
command with a warning if no experiment is running.
collector profile { on | off }
Enable or disable collection of clock-based profiling data. If
an experiment is active, ignore the command with a warning.
Default is enabled.
collector profile timer value
Set the profiling timer interval to value. The value can be an
integer or a floating-point number, with a suffix of u for val‐
ues in microseconds, or m for values in milliseconds. If no
suffix is used, assume the value to be in milliseconds. Set the
default interval to 10 milliseconds.
The interval value can also be given as one of the strings "hi"
or "high" for profiling at a 1 millisecond interval, "lo" or
"low" for profiling at a 100 millisecond interval, or "on" for
profiling at a 10 millisecond interval. These interval values
are approximate.
If the value is smaller than the system clock profiling minimum
set it to the minimum; if it is not a multiple of the clock pro‐
filing resolution round down to the nearest multiple of the
clock resolution. If it exceeds the clock profiling maximum,
report an error. If it is negative or zero, report an error.
If an experiment is active, ignore the command with a warning.
collector hwprofile { on | off }
Enable or disable hardware-counter overflow profiling. On sys‐
tems whose hardware or operating system does not support hard‐
ware-counter overflow profiling, return an error on detecting an
attempt to enable it. If an experiment is active, ignore the
command with a warning. Default is disabled.
collector hwprofile list
Print a usage summary, including the default configuration of
the experiment. If the processor supports hardware counter pro‐
filing, print two lists containing information about hardware
counters. The first list will contain "well known" hardware
counters; the second list will contain raw hardware counters.
For example, the collector hwprofile list command invoked on a
Sun OS SPARC-based system would produce an output similar to the
following:
Well known HW counters available for profiling:
cycles[/{0|1}],9999991 (`CPU Cycles', alias for Cycle_cnt; CPU-cycles)
insts[/{0|1}],9999991 (`Instructions Executed', alias for Instr_cnt; events)
icm[/1],100003 (`I$ Misses', alias for IC_miss; events)
...
Raw HW counters available for profiling:
Cycle_cnt[/{0|1}],1000003 (CPU-cycles)
Instr_cnt[/{0|1}],1000003 (events)
Dispatch0_IC_miss[/0],1000003 (CPU-cycles)
...
collector hwprofile counter ctr_def...[,ctr_n_def]
Collect hardware counter overflow profiles. The number of
counter definitions, (ctr_def through ctr_n_def) is processor-
dependent. For example, on an UltraSPARC III system, up to two
counters may be programmed; on an Intel Pentium 4 with Hyper‐
threading, up to 18 counters are available. The user can ascer‐
tain the maximum number of hardware counters definitions for
profiling on a target system, and the full list of available
hardware counters, by running the collect -h command without any
other arguments. This option is not available on Linux systems.
Each counter definition takes one of the following forms,
depending on whether attributes for hardware counters are sup‐
ported on the processor:
1. [+]ctr[/reg#],interval
[+]ctr[/reg#] interval
Examples:
collector hwprofile counter cycles,on,insts
collector hwprofile counter cycles on insts
Note: For historical reasons, a space can still be used as
the delimiter between hardware counters.
2. [+]ctr[~attr=val]...[~attrN=valN][/reg#],interval
Example:
collector hwprofile counter FP_dispatched_fpu_ops~umask=0x3/2,10007
enables the Floating Point Add and Multiply operations to be
tracked. (For more details on valid attribute values, refer to
the processor documentation). The "/2" value specifies instruc‐
tions to be executed using the second register of the hardware.
The CPU cycle profiling is done at an interval rate of 10007
events.
The meanings of the counter definition options are as follows:
Value Meaning
+ Optional parameter that can be applied to memory-
related counters. Causes collect to backtrack in an
attempt to find the instruction that triggered the
overflow, and to find the virtual and physical
addresses of the memory reference. Backtracking will
only work with counters of type load, store, or load-
store, as displayed in the counter list obtained by
running the collect -h command without any other argu‐
ments.
ctr Processor-specific counter name. The user can ascer‐
tain the list of counter names by running the collect
-h command without any other arguments.
attr=val On some processors, attribute options can be associ‐
ated with a hardware counter. If the processor sup‐
ports attribute options, then running collect -h with‐
out any other arguments will specify the counter defi‐
nition, ctr_def, in the second form listed above, and
provide a list of attribute names to use for attr.
Value val can be in decimal or hexadecimal format.
Hexadecimal format numbers are in C program format
where the number is prepended by a zero and lower-case
x (0xhex_number).
reg# Hardware register to use for the counter. If not spec‐
ified, collect will attempt to place the counter into
the first available register and as a result, may be
unable to place subsequent counters due to register
conflicts. If the user specifies more than one
counter, the counters must use different registers.
The list of allowable register numbers can be ascer‐
tained by running the collect -h command without any
other arguments.
interval
Sampling frequency, set by defining the counter over‐
flow value. Valid values are as follows:
Value Meaning
on Select the default rate, which can be deter‐
mined by running the collect -h command
without any other arguments. Note that the
default value for all raw counters is the
same, and may not be the most suitable value
for a specific counter.
hi Set interval to approximately 10 times
shorter than on.
lo Set interval to approximately 10 times
longer than on.
value Set interval to a specific value, specified
in decimal or hexadecimal format.
An experiment can specify both hardware counter profiling and clock-
based profiling. If hardware counter profiling is specified, but
clock-based profiling is not explicitly specified, turn off clock-
based profiling.
collector synctrace { on | off }
Enable or disable collecting of synchronization tracing data.
Default is off. If an experiment is active, ignore the com‐
mand with a warning.
collector synctrace threshold value
Set the threshold for synchronization delay tracing according
to the given value, which can be one of the following:
Value Meaning
calibrate or on
Use a calibrated threshold, determined at runtime.
off Turn off synchronization delay tracing.
n Use an threshold value of n microseconds. A zero
value enables tracing of all events.
The default setting is calibrate. If an experiment is
active, ignore the command with a warning.
collector mpitrace { on | off }
Enable or disable collecting of MPI tracing data. Default is
off. If an experiment is active, ignore the command with a
warning. MPI tracing under dbx is not recommended.
collector heaptrace { on | off }
Enable or disable collecting of heap tracing data. Default is
off. If an experiment is active, ignore the command with a
warning.
collector tha { on | all | <option> | off }
Control collecting of Thread Analyzer data. Default is off.
If an experiment is active, ignore the command with a warn‐
ing. The target executable must be instrumented for datarace
detection; see the tha(1) man page for more detail.
<option> is a comma-separated list of the Thread Analyzer
data options. Values for <option> include race and deadlock,
which can be specified individually or combined as dead‐
lock,race or race,deadlock. See the collect() man page for
more information.
collector archive { on | off | copy }
Set the mode for archiving the experiment. The default is on,
corresponding to normal archiving. If the mode is set to off,
do no archiving. If the mode is set to copy, copy all load
objects used into the experiment. A user that moves the
experiment to a different machine, or reads it from another
machine, should enable the copying of all load objects. If an
experiment is active, ignore the command with a warning.
collector limit value
Limit the amount of profiling data recorded to value
megabytes. The limit applies to the sum of all profiling
data and tracing data, but not to sample points. The limit is
only approximate, and can be exceeded. When the limit is
reached, record no more profiling or tracing data, but keep
the experiment open and record samples until the target
process terminates. If an experiment is active, ignore the
command with a warning.
By default, there is no limit on the amount of data recorded.
collector status
Report on the status of any open experiment.
collector show
Show the current settings of all collector control variables.
collector sample { periodic | manual }
Set the sampling mode to either periodic or manual. If peri‐
odic is specified, record samples at the current sampling
frequency. If manual is specified, record periodic samples.
Samples can be recorded manually using collector sample
record regardless of which mode is specified. If an experi‐
ment is active, ignore the command with a warning.
collector sample record [name]
Record a sample, with the optional label name. If an experi‐
ment is not active, ignore the command with a warning.
collector sample period value
Set the sampling frequency to value, given in seconds. If an
experiment is active, ignore the command with a warning.
collector dbxsample { on | off }
Control the collection of samples when dbx stops the target
process. For the on option, collect a sample each time dbx
stops the target process; if off , collect no samples.
Default is on.
collector store directory name
Set the collector directory to name. If an experiment is
active, ignore the command with a warning.
collector store experiment name
Set the output experiment name to name. If an experiment is
active, ignore the command with a warning. If a name is not
specified, use the default name. The default name is
described in the collect(1) man page.
collector store group name
Set the experiment group name to name. If an experiment is
active, ignore the command with a warning.
collector version
Report the version of libcollector.so that would be used to
collect data.
help collector
Prompt the user about the various collector commands avail‐
able.
OBSOLETE DBX COMMANDS
A few commands previously accepted by dbx are now obsolete; they are:
collector enable_once
Ignored with a warning. The command used to allow enabling data
collection for just one run.
collector close
Treated as collector disable if an experiment is running.
Ignored with a warning if no experiment is running.
collector quit
Treated as collector disable if an experiment is running.
Ignored with a warning if no experiment is running.
collector address_space { on | off }
Address space data is no longer supported. The command is
ignored with a warning.
collector store filename name
Accepted as collector store experiment, for compatibility. Sets
the output experiment name to name.
FOLLOWING DESCENDANT PROCESSES
When a process that is collecting performance data creates a descendant
process, the collector continues to collect data on the parent process,
with the following exception: If a process calls any variant of exec,
the experiment terminates abnormally if the exec succeeds, and contin‐
ues if the exec fails. In either case, the experiment can be read by
the performance analysis tools.
If you want to record data for a descendant process, you should attach
dbx to the newly created process and then start an experiment on the
descendant process using collector enable. If you want to automati‐
cally collect data on all descendant processes, use the collect(1) com‐
mand.
ATTACHING TO A PROCESS
You can attach dbx to a process, and use the collector commands to col‐
lect performance data from it.
After the executable has been started, determine its PID, and attach
dbx to it, using the the command
dbx executable-name PID
Be sure to include the process' executable name. At that point, you
can enable data collection.
If you started the executable from dbx without enabling data collec‐
tion, you can pause it from dbx at any time, and then enable data col‐
lection, but subject to the same restrictions as attaching.
Because of dbx bug 7077536, starting the collector on a multithreaded
target which is paused in a system call may cause the call to return
prematurely, without indicating an error, and may result in unpre‐
dictable behavior.
Collecting data by attaching to applications that install signal han‐
dlers or use libcpc.so may not work properly, since that functionality
relies on having the user code call the collector's wrapper around the
real routines referenced, rather than the routines themselves. Simi‐
larly, collecting trace data (Synchronization tracing, Heap tracing, or
MPI tracing), or following descendant processes may not work. Only
clock- and hwc-profile experiments will work on a process attached to
by dbx. A workaround for those difficulties is to use the -y sig flag
to collect to start the process, then enable data collection by sending
the specified signal, sig, to the target.
SEE ALSOanalyzer(1), collect(1), dbx(1), er_archive(1), er_cp(1), er_export(1),
er_mv(1), er_print(1), er_rm(1), tha(1), libcollector(3), and the Per‐
formance Analyzer manual.
September 2011 collector(1)