Man Page collector.1
NAME
collector - subcommands of dbx used for performance data
collection
SYNOPSIS
dbx
AVAILABILITY
Part of Forte(TM) C, Forte C++, and Forte for High Perfor-
mance Computing.
DESCRIPTION
The term collector is used to describe the data collection
features in dbx or accessible from the Sun WorkShop(TM)
Debugging window and the runtime support for those features
in libcollector.so.
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:
collector { enable | disable }
Enable or disable data collection.
If no process is active, these commands con-
trol whether or not an experiment is collected
when a process is started. If the mode is
disable, no performance data is collected. If
the mode is enable, data is collected for all
subsequent runs.
If a process is running, but no experiment is
active, enable starts an experiment. If dis-
able is given, it is ignored with a warning.
If a process is running and an experiment is
active, disable terminates the experiment. If
enable is given, it is ignored with a warning.
If an experiment is terminated, but the pro-
cess is left running, enable starts a new
experiment.
collector pause
Temporarily stop recording data during an
experiment. Ignored with no warning if
recording of data is already paused. Ignored
with a warning if no experiment is running.
collector resume
Resume recording data during an experiment.
Ignored with no warning if recording of data
is not paused. Ignored with a warning if no
experiment is running.
collector profile { on | off }
Enable or disable collection of clock-based
profiling data. Default is enabled. If an
experiment is active, the command is ignored
with a warning.
collector profile timer <value>
Set the profiling timer interval to <value>,
given in milliseconds. Default is 10 ms. If
an experiment is active, the command is
ignored with a warning.
collector synctrace { on | off }
Enable or disable collecting of synchroniza-
tion tracing data. Default is off. If an
experiment is active, the command is ignored
with a warning.
collector synctrace threshold <value>
Set the threshold for synchronization delay
tracing according to the given <value>.
<value> = "calibrate" means use a calibrated
threshold, determined at runtime.
<value> = <number> means use a threshold of
<number>, given in microseconds.
Setting <number> to "0" means "trace all
events".
The default setting is "calibrate".
If an experiment is active, the command is
ignored with a warning.
collector hwprofile { on | off }
Enable or disable HW-counter-overflow profil-
ing. On systems whose HW or OS does not sup-
port HW-counter-overflow profiling, an error
is returned on attempting to enable it. If an
experiment is active, the command is ignored
with a warning.
collector hwprofile list
Return a list of available counters by name,
with two numeric settings, one for a normal
interval, and one for a higher-resolution
interval.
collector hwprofile counter <name> <value> [<name2> <value2>]
Set the HW counter profiling to the event with
the given <name>, and an overflow interval
given by <value>. If <value> is zero the
default value is used. The default choice for
<name> is "cycles", at the normal profiling
interval. If an experiment is active, the
command is ignored with a warning. If a
second name and interval are specified, dual
counter profiling is performed; the two
counters must be on different event registers.
collector status
Report on the status of any opened experiment.
collector show
Show the current settings of all collector
control variables.
collector sample { periodic | manual }
Set the sampling mode to either periodic, or
to manual. If an experiment is active, the
command is ignored with a warning.
collector sample period <value>
Set the sampling frequency to <value>, given
in seconds. If an experiment is active, the
command is ignored with a warning.
collector store directory <value>
Set the collector directory to <value>. If an
experiment is active, the command is ignored
with a warning.
collector store filename <value>
Set the output experiment name to <value>. If
an experiment is active, the command is
ignored with a warning. If a name is not
specified, the default name is used. The
default name is described in the collect(1)
man page.
collector store group <value>
Set the experiment group name to <value>. If
an experiment is active, the command is
ignored with a warning.
collector address_space { on | off }
Enable or disable collecting address space
(page reference and modified information)
data. Default is off. If an experiment is
active, the command is ignored with a warning.
NOTE: address space data is only available on
SPARC machines.
collector help
Prompt the user about the various collector
commands available.
help collector
Prompt the user about the various collector
commands 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 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.
Attaching to and Collecting Data from a Multithreaded Application
You can attach dbx to a multithreaded executable, and use
the collector commands to collect performance data from it.
If you want to collect thread synchronization delay data,
you must preload the library libcollector.so before you
start your executable, so that the collector's wrapper
around the real synchronization routines is referenced,
rather than the real routines themselves. To do so, set the
value of the environment variable LD_PRELOAD:
setenv LD_PRELOAD $DIST/lib/libcollector.so (csh)
or
LD_PRELOAD=$DIST/lib/libcollector.so; export LD_PRELOAD (sh or ksh)
For SPARC-v9 executables, you should use:
setenv LD_PRELOAD $DIST/lib/v9/libcollector.so (csh)
or
LD_PRELOAD=$DIST/lib/v9/libcollector.so; export LD_PRELOAD (sh or ksh)
where $DIST is the directory that contains the installed
distribution of the tools (normally, /opt/SUNWspro ). If
you are only collecting clock- or HW-counter-overflow pro-
filing data, you do not need to preload the collector
library, although you may do so.
Note that you would normally remove the LD_PRELOAD setting
after the run, to avoid having it in effect for all other
programs started from the same shell.
After the executable has been started, you should determine
its PID, and attach dbx to it. 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.
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), er_src(1),
workshop(1), libcollector(3), and
Analyzing Program Performance With Sun WorkShop.