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 now works for applications written in the Java(TM) programming language. (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.
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".
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 millisecond interval, or "on" for profiling at a 10 millisecond interval. These interval values are approximate.
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.
Print a usage summary, including the default configuration of the experiment. If the processor supports hardware counter profiling, print two lists containing information about hardware counters. The first list will contain "aliases" hardware counters; the second list will contain raw hardware counters. Following the list, the name of the reference manual for the chip, and the default counter set defined for the chip will be printed.
For example, the collector hwprofile list command invoked will produce output similar to the following:
Aliased 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)
...
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, or by issuing the collector hwprofile list command.
Four special names can be used for counters, on specifies using the pre-defined counter set for the chip, hi|high specifies using that set at high-resolution, lo|low specifies using that set at low-resolution, and off specifies turning off HW counter profiling. If the special names hi or lo are used, specifying the default counter set for that chip with either high- or low-resolution profiling, the default clock-profiling resolution will be also be set to high- or low-resolution. An explicit setting of the clock resolution will be respected.
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#],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.
[+|-]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 profiling is done at an interval rate of 10007 events.
The meanings of the counter definition options are as follows:
Optional parameter that can be applied to memory-related counters. + requests data- and memory-space profiling data be recorded. - requests that it not be recorded.
Memory-related counters are those with type load, store, or load-store, as displayed in the counter list obtained by running the collect -h command without any other arguments. Some such counters are also labeled precise.
For precise counters, on either SPARC or x86, the + is not needed; data- and memory-space data will be recorded by default. A - will turn off data- and memory-space data.
For SPARC only, a + specified on a non-precise memory counter will cause collect to backtrack in an attempt to find the instruction that triggered the overflow, and to find the virtual and physical addresses of the memory reference. Such data is not recorded by default and a - is not needed to turn it off.
Processor-specific counter name. The user can ascertain the list of counter names by running the collect -h command without any other arguments.
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 arguments 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 hexadecimal format. Hexadecimal format numbers are in C program format where the number is prepended by a zero and lower-case x (0xhex_number).
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 subsequent 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.
Sampling frequency, set by defining the counter overflow value. Valid values are as follows:
Select the default rate, which can be determined by running the collect -h command without any other arguments. Note that the default value for all raw counters is the same, and may not be the most suitable value for a specific counter.
Set interval to approximately 10 times shorter than on.
Set interval to approximately 10 times longer than on.
Set interval to a specific value, specified in decimal or hexadecimal format.
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, (ctr_def through ctr_n_def) is processor-dependent, as 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.
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 sample signal. If an experiment is active, ignore the command with a warning.
MPI tracing is not 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.
Set the mode for archiving the experiment. The default is on, corresponding to normal archiving, with copying of the target and all shared objects referenced in the experiment. For Java experiments, all .jar files are also copied. If the mode is set to off, do no archiving. If the mode is set to src, archive all source files that can be found as well. If the mode is set to usedsrc, archive all source files that are referenced in the data and can be found as well. A user that moves the experiment to a different machine, or reads it from another machine, should enable the archiving/copying of all load objects. If an experiment is active, ignore the command with a warning.
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 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 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.
Record a sample, with the optional label name. If an experiment is not active, ignore the command with a warning.
Set the sampling frequency to value, given in seconds. If an experiment is active, ignore the command with a warning.
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.
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 automatically collect data 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 the command
dbx executable-name PID
Be sure to include the process' executable name. At that point, you can enable data collection.
You may also use the command
collect -P PID
to attach to a process and collect data.
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 PID, you should also set "-j on" with the collect command. You may not 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