Man Page 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 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, 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
being collected, enable starts an experiment.
If disable is given, it is ignored with a
warning.
If a process is running and an experiment is
being collected, disable terminates the exper-
iment. 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 zero 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 hardware-counter overflow
profiling. On systems whose hardware or
operating system does not support hardware-
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 three numeric settings, one for a normal
interval, one for a higher-resolution inter-
val, and one for a lower-resolution interval.
collector hwprofile counter name value [name2 value2]
Set the hardware 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 a second name and interval are
specified, dual counter profiling is per-
formed; the two counters must be on different
event registers. If an experiment is active,
the command is ignored with a warning.
collector heaptrace { on | off }
Enable or disable collecting of heap tracing
data. Default is off. If an experiment is
active, the command is ignored with a warning.
collector mpitrace { on | off }
Enable or disable collecting of MPI tracing
data. Default is off. If an experiment is
active, the command is ignored 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, no more profiling or tracing
data is recorded, but the experiment remains
open and samples are recorded until the target
process terminates. If an experiment is
active, the command is ignored with a warning.
The default limit on the amount of data
recorded is 2000 Mbytes. To remove the limit,
set value to zero.
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, samples are
recorded at the current sampling frequency.
If manual is specified, periodic samples are
not recorded. Samples can be recorded manu-
ally using collector sample record regardless
of which mode is specified. If an experiment
is active, the command is ignored with a warn-
ing.
collector sample record [name]
Record a sample, with the optional label name.
If an experiment is not 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 com-
mand is ignored with a warning.
collector dbxsample { on | off }
Controls the collection of samples when dbx
stops the target process. If on, a sample is
collected each time dbx stops the target pro-
cess; if off, no such samples are collected.
Default is on.
collector store directory name
Set the collector directory to name. If an
experiment is active, the command is ignored
with a warning.
collector store experiment name
Set the output experiment name to name. 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 name
Set the experiment group name to name. If an
experiment is active, the command is ignored
with a warning.
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.
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 is ter-
minated 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.
If you want to collect any kind of tracing data or ensure
that data collection succeeds for applications that install
signal handlers or use libcpc.so, you must preload the
library libcollector.so before you start your executable, so
that the collector's wrapper around the real routines is
referenced, rather than the routines themselves. To do so,
set the value of the environment variable LD_PRELOAD to
libcollector.so and set the value of the environment vari-
able LD_LIBRARY_PATH to /opt/SUNWspro/lib. If you are using
SPARC[tm] V9 64-bit architecture, you must also set the
environment variable LD_LIBRARY_PATH_64 to
/opt/SUNWspro/lib/v9. If the performance tools are not
installed in /opt/SUNWspro/lib, ask your system administra-
tor for the correct path. If you are only collecting
clock-based data or hardware-counter overflow data, you do
not need to preload the collector library, but preloading
the collector library ensures that the data collection is
protected from various problems.
To avoid having the LD_PRELOAD setting in effect for all
other programs started from the same shell, remove the
LD_PRELOAD setting after the data collection run.
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), libcollec-
tor(3), and the manual
Program Performance Analysis Tools