svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
collector(1)
collector(1) User Commands collector(1)
NAME
collector - subcommands of dbx used for performance data collection
SYNOPSIS
(dbx) collector subcommand [ options ]
where (dbx) is the interactive prompt in 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 works for applications written in the Java program‐
ming language.
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 col‐
lected, 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
on.
collector profile timer {lo | on | hi | value}
Turn on profiling at the specified rate.
lo[w]
Turn on clock-based profiling with a per-thread maximum rate of
approximately 10 samples per second.
on
Turn on clock-based profiling with a per-thread maximum rate of
approximately 100 samples per second.
hi[gh]
Turn on clock-based profiling with a per-thread maximum rate of
approximately 1000 samples per second.
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. The
default interval is 10 milliseconds.
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
warning. Default is disabled.
collector hwprofile list
If the processor supports hardware counter profiling, print lists
of convenient aliases for certain hardware counters names, raw
names of all available counters, and attributes of these counters.
Output is similar to:
Aliases for most useful HW counters:
alias raw name type units regs description
cycles Cycles_user CPU-cycles 0123 CPU Cycles
insts Instr_all events 0123 Instructions Executed
c_stalls Commit_0_cyc CPU-cycles 0123 Stall Cycles
loads Instr_ld precise load-store events 0123 Load Instructions
stores Instr_st precise load-store events 0123 Store Instructions
dcm DC_miss_commit precise load-store events 0123 L1 D-cache Misses
...
Raw HW counters:
name type units regs description
Sel_pipe_drain_cyc CPU-cycles 0123
Sel_0_wait_cyc CPU-cycles 0123
Sel_0_ready_cyc CPU-cycles 0123
...
Attributes available for use with Raw HW counters:
system
user
...
collector hwprofile counter ctr_def[,ctr_def]...
Collect hardware counter overflow profiles. The maximum number of
ctr_def counter definitions you can specify is processor-dependent.
You can determine the maximum number of hardware counter defini‐
tions for profiling on a target system by checking the regs column
in the collector hwprofile list output -- for example, four regis‐
ters are shown (0123) in the case above.
Four special names can be used in place of the ctr_def list:
on specifies using the predefined default counter set for
the chip
hi|high specifies using that default set at high-resolution
lo|low specifies using that default set at low-resolution
off specifies turning off HW counter profiling
If you use the special names hi or lo for high- or low-resolution
hardware counter profiling, the default clock-profiling resolution
is also set to high- or low-resolution. However, if you explicitly
set the clock resolution, that resolution is used for clock profil‐
ing.
Except for those special names, each counter definition takes one
of the following forms, depending on whether attributes for hard‐
ware counters are supported on the processor:
1.
[+|-]ctr[/reg#],rate
[+|-]ctr[/reg#] rate
Examples:
collector hwprofile counter cycles,auto,insts
collector hwprofile counter cycles auto insts
Note: For historical reasons, a space can still be used
as the delimiter between hardware counters.
2.
[+|-]ctr[~attr=val]...[~attrN=valN][/reg#],rate
Example:
collector hwprofile counter FP_dispatched_fpu_ops~umask=0x3/2
This example 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" specifies using counter register 2. The sam‐
pling rate will be base on the collector profile timer
setting.
The meanings of the counter definition options are as follows:
+|-
Optional parameter that can be applied to precise, memory-
related counters. A + is the default. A - means to collect only
normal hardware-counter information and not the extra informa‐
tion that is used for memoryspace and dataspace profiling.
Precise counters are labeled precise in the list displayed by
the command 'collector hwprofile list'. Memory-related precise
counters are shown with type load, store, or load-store.
ctr
Processor-specific counter name. You can see the list of
counter names by running collector hwprofile list.
attr=val
On some processors, attribute options can be associated with a
hardware counter, and running collector hwprofile list displays
a list of attribute names. Value val can be in decimal or hexa‐
decimal format. Hexadecimal format numbers are in C program
format where the number is prepended by a zero and lower-case x
(e.g., 0x3f).
reg#
On Oracle Solaris, hardware register to use for the counter. If
a register is not specified, collect attempts to place the
counter into the first available register and as a result,
might be unable to place subsequent counters due to register
conflicts. If you specify more than one counter, the counters
must use different registers. You can display the list of
allowable register numbers by running collector hwprofile list.
rate
The sampling frequency. Valid values are as follows:
auto Match the rate used by clock-profiling. If clock-
profiling is disabled, use the per-thread maximum
rate of approximately 100 samples per second. auto
is the default and preferred setting.
lo[w] Use the per-thread maximum rate of approximately
10 samples per second.
hi[gh] Use the per-thread maximum rate of approximately
1000 samples per second.
value Specify a fixed event interval value to trigger a
sample, rather than a sampling rate. When specify‐
ing value, note that the actual frequency is
dependent on the selected counter and the program
under test.
An experiment can specify both hardware counter profiling and
clock-based profiling. Specifying hardware counter profiling will
not disable clock-based profiling by default.
collector hwprofile addcounter ctr_def[,ctr_def]...
Add additional counters for hardware counter overflow profiles. The
number of counter definitions is processor-dependent, as described
above. hwprofile counter discards any previous counters set; hwpro‐
file addcounter appends the new list to the old one.
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[,scope]
Set the threshold for synchronization delay tracing according to
the given value, which can be one of the following:
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.
The allowed values for optionally setting synchronization tracing
scope are:
n
Trace native APIs.
j
Trace Java APIs
nj
Trace native and Java APIs
By default, trace both native and Java APIs.
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 iotrace { on | off }
Enable or disable collecting of I/O tracing data. Default is off.
If an experiment is active, ignore the command with a warning.
collector java { on | off }
Enable or disable collecting of Java data. Default is off. If an
experiment is active, ignore the command with a warning. See the
section "JAVA PROFILING" below.
collector duration duration
Collect data for the specified duration. duration can be a single
number, followed by either m, specifying minutes, or s, specifying
seconds (default), or two such numbers separated by a - sign. If
one number is given, data is collected from the start of the run
until the given time; if two numbers are given, data is collected
from the first time to the second. If the second time is zero, data
is collected until the end of the run. If two non-zero numbers are
given, the first must be less than the second. If an experiment is
active, ignore the command with a warning.
collector pausesig signal[ resume]
Define the pause resume signal; if the optional resume is added,
start resumed, otherwise, start paused. If an experiment is active,
ignore the command with a warning.
collector samplesig signal
Define the signal to trigger a process-wide resource-utilization
sample. If an experiment is active, ignore the command with a warn‐
ing.
collector mpitrace { on | off }
MPI tracing is no longer supported.
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(1) man page for more information.
collector archive { on | src | usedsrc | off }
Control whether to perform archiving as part of data collection.
Archiving is required to make an experiment self-contained and por‐
table.
The supported options are as follows:
on Copy load objects (the target and any shared objects it
uses) into the experiment. Also copy any ancillary files
(.anc) and object files (.o) which have Stabs or DWARF
information not in the load object.
src In addition to copying load objects as in archive on,
copy into the experiment all source files and ancillary
files (.anc) that can be found.
usedsrc Similar to archive on, but only copy source files,
ancillary files (.anc), and load objects that are needed
for analytics and can be found. This option might
require additional processing time, but can result in
smaller experiment sizes.
off Do not copy or archive load objects or source files into
the experiment.
Archiving will not be performed in the following circumstances:
o A profiled process is terminated before it exits nor‐
mally
o archive off is specified
In such cases, you must run er_archive explicitly on the same
machine where the profiling data was recorded.
The minimum archiving required that enables an experiment to be
accessed on another machine is archive on. When using this option,
note that on does not copy any sources or object files (.o's); it
is your responsibility to ensure that those files are accessible
from the machine where the experiment is being examined, and that
they are not changed or rebuilt after the experiment was recorded.
The default setting is on.
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 process-wide resource-utilization samples. 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 of process-wide resource utilization to either
periodic or manual. If periodic is specified, record samples at the
current sampling frequency. If manual is specified, disable sample
periodically. Samples can be recorded manually using collector sam‐
ple record regardless of which mode is specified. If an experiment
is active, ignore the command with a warning.
collector sample record [name]
Sample process-wide resource utilization with the optional label
name. If an experiment is not active, ignore the command with a
warning.
collector sample period value
Set the period for sampling process-wide resource utilization to
value, given in seconds. If an experiment is active, ignore the
command with a warning.
collector dbxsample { on | off }
Control the sampling of process-wide resource utilization when dbx
stops the target process. For the on option, sample each time dbx
stops the target process; if off, do not sample. 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 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 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 collect data
automatically on all descendant processes, use the collect(1) command.
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 following command:
dbx executable-name PID
Be sure to include the process' executable name. At that point, you can
enable data collection.
You can also use the following command to attach to a process and col‐
lect data.
collect -P PID
When attaching to a process owned by a user other than the user invok‐
ing dbx or collect -P, the umask of the user wanting to attach to the
process must be set so as to allow writing by the user owning the
process to which you are attaching. If it is not properly set, data
collection will fail with a message that the directory is not writable.
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.
Note -
On Linux, attaching to a multithreaded process, including Java, will
not properly collect data. Data for the thread that wasattached to
will be captured, but not data for other threads.
JAVA PROFILING UNDER DBX
To profile a Java application under dbx from its start, you should use
the JVM you want to run with as the target of dbx, issue a "collector
java on" command, set the profiling parameters for the data you want to
collect, issue a "collector enable" command, and then launch the target
with a "run" command. Any arguments for the JVM should be given with
the run command, including the name of the class or jar file for the
Java application.
To profile a running application, whether you started it under dbx or
you have used dbx to attach to the running JVM, you first stop the tar‐
get (or wait for it to stop at a breakpoint), and then issue the "col‐
lector java on", and any profiling parameter commands, then "collector
enable" and "cont".
To use collect with the "-P PID" parameter to attach to a JVM with the
given process ID, you should also set "-j on" with the collect command.
You cannot use "-j" with a path to a JVM, nor a "-J" argument to spec‐
ify Java runtime parameters.
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), libcollector(3)
Performance Analyzer manual
Studio 12.6 August 2016 collector(1)