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 functional-
ity 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 collect 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 col-
lected, 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 exper-
iment 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 values 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 mil-
lisecond interval, or "on" for profiling at a 10 mil-
lisecond interval. These interval values are approxi-
mate.
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 profiling 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 systems whose hardware or operating system does not
support hardware-counter overflow profiling, return an
error on detecting an attempt to enable it. If an
experiment is active, ignore the command with a warn-
ing. Default is disabled.
collector hwprofile list
Print a usage summary, including the default configura-
tion of the experiment. If the processor supports
hardware counter profiling, 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 Hyperthreading, up to 18 counters
are available. The user can ascertain 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 avail-
able on Linux systems.
Each counter definition takes one of the following
forms, depending on whether attributes for hardware
counters are supported 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 instructions to be executed using
the second register of the hardware. The CPU cycle pro-
filing 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 instruc-
tion 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 arguments.
ctr Processor-specific counter name. The user can
ascertain the list of counter names by run-
ning the collect -h command without any other
arguments.
attr=val On some processors, attribute options can be
associated with a hardware counter. If the
processor supports attribute options, then
running collect -h without any other argu-
ments will specify the counter definition,
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 hexade-
cimal 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 specified, collect will attempt to place
the counter into the first available register
and as a result, may be unable to place sub-
sequent 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
ascertained by running the collect -h command
without any other arguments.
interval
Sampling frequency, set by defining the
counter overflow value. Valid values are as
follows:
Value Meaning
on Select the default rate, which can
be determined by running the col-
lect -h command without any other
arguments. Note that the default
value for all raw counters is the
same, and may not be the most suit-
able 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 profil-
ing and clock-based profiling. If hardware counter pro-
filing 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 command with a warning.
collector synctrace threshold value
Set the threshold for synchronization delay trac-
ing 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 experi-
ment 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 warning. 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 deadlock,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 experi-
ment 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 tar-
get 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 periodic 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
experiment is active, ignore the command with a
warning.
collector sample record [name]
Record a sample, with the optional label name. If
an experiment 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 exper-
iment is active, ignore the command with a warn-
ing.
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 com-
mands available.
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 ena-
bling data collection for just one run.
collector close
Treated as collector disable if an experiment is run-
ning. Ignored with a warning if no experiment is run-
ning.
collector quit
Treated as collector disable if an experiment is run-
ning. Ignored with a warning if no experiment is run-
ning.
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 compatibil-
ity. 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 continues 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 collec-
tor enable. If you want to automatically collect data on
all descendant processes, use the collect(1) command.
ATTACHING TO A PROCESS
You can attach dbx to a process, and use the collector com-
mands to collect 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
collection, you can pause it from dbx at any time, and then
enable data collection, but subject to the same restrictions
as attaching.
Because of dbx bug 7077536, starting the collector on a mul-
tithreaded target which is paused in a system call may cause
the call to return prematurely, without indicating an error,
and may result in unpredictable behavior.
Collecting data by attaching to applications that install
signal handlers 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. Similarly, 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 pro-
cess attached to by dbx. A workaround for those difficul-
ties is to use the -y sig flag to collect to start the pro-
cess, then enable data collection by sending the specified
signal, sig, to the target.
SEE ALSO
analyzer(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), lib-
collector(3), and the Performance Analyzer manual.