collector - subcommands of dbx used for performance data collection
(dbx) collector subcommand [ options ]
where (dbx) is the interactive prompt in dbx
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 programming language.
The data collected is described in the collect(1) man page. The collect command can collect data without using dbx.
The commands accepted by dbx to support performance data collection are as follows.
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.
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.
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.
Enable or disable collection of clock-based profiling data. If an experiment is active, ignore the command with a warning. Default is on.
Turn on profiling at the specified rate.
Turn on clock-based profiling with a per-thread maximum rate of approximately 10 samples per second.
Turn on clock-based profiling with a per-thread maximum rate of approximately 100 samples per second.
Turn on clock-based profiling with a per-thread maximum rate of approximately 1000 samples per second.
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. 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.
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.
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
...
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 definitions for profiling on a target system by checking the regs column in the collector hwprofile list output -- for example, four registers are shown (0123) in the case above.
Four special names can be used in place of the ctr_def list:
specifies using the predefined default counter set for the chip
specifies using that default set at high-resolution
specifies using that default set at low-resolution
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 profiling.
Except for those special names, each counter definition takes one of the following forms, depending on whether attributes for hardware counters are supported on the processor:
[+|-]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.
[+|-]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 sampling 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 information 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.
Processor-specific counter name. You can see the list of counter names by running collector hwprofile list.
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 hexadecimal format. Hexadecimal format numbers are in C program format where the number is prepended by a zero and lower-case x (e.g., 0x3f).
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.
The sampling frequency. Valid values are as follows:
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.
Use the per-thread maximum rate of approximately 10 samples per second.
Use the per-thread maximum rate of approximately 1000 samples per second.
Specify a fixed event interval value to trigger a sample, rather than a sampling rate. When specifying 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.
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; hwprofile addcounter appends the new list to the old one.
Enable or disable collecting of synchronization tracing data. Default is off. If an experiment is active, ignore the command with a warning.
Set the threshold for synchronization delay tracing according to the given value, which can be one of the following:
Use a calibrated threshold, determined at runtime.
Turn off synchronization delay tracing.
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:
Trace native APIs.
Trace Java APIs
Trace native and Java APIs
By default, trace both native and Java APIs.
Enable or disable collecting of heap tracing data. Default is off. If an experiment is active, ignore the command with a warning.
Enable or disable collecting of I/O tracing data. Default is off. If an experiment is active, ignore the command with a warning.
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.
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.
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.
Define the signal to trigger a process-wide resource-utilization sample. If an experiment is active, ignore the command with a warning.
MPI tracing is no longer supported.
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.
Control whether to perform archiving as part of data collection. Archiving is required to make an experiment self-contained and portable.
The supported options are as follows:
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.
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.
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.
Do not copy or archive load objects or source files into the experiment.
Archiving will not be performed in the following circumstances:
A profiled process is terminated before it exits normally
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.
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.
Report on the status of any open experiment.
Show the current settings of all collector control variables.
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 sample record regardless of which mode is specified. If an experiment is active, ignore the command with a warning.
Sample process-wide resource utilization with the optional label name. If an experiment is not active, ignore the command with a warning.
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.
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.
Set the collector directory to name. If an experiment is active, ignore the command with a warning.
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.
Set the experiment group name to name. If an experiment is active, ignore the command with a warning.
Report the version of libcollector.so that would be used to collect data.
Prompt the user about the various collector commands available.
A few commands previously accepted by dbx are now obsolete; they are:
Ignored with a warning. The command used to allow enabling data collection for just one run.
Treated as collector disable if an experiment is running. Ignored with a warning if no experiment is running.
Treated as collector disable if an experiment is running. Ignored with a warning if no experiment is running.
Address space data is no longer supported. The command is ignored with a warning.
Accepted as collector store experiment, for compatibility. Sets the output experiment name to name.
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 collector enable. If you want to collect data automatically on all descendant processes, use the collect(1) command.
You can attach dbx to a process, and use the collector commands to collect 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 collect data.
collect -P PID
When attaching to a process owned by a user other than the user invoking 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 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 multithreaded 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 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.
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 target (or wait for it to stop at a breakpoint), and then issue the "collector 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 specify Java runtime parameters.
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