These options control the types of data that are collected. See Data the Collector Collects for a description of the data types.
If you do not specify data collection options, the default is -p on, which enables clock profiling with the default profiling interval of approximately 10 milliseconds.
If you explicitly disable clock profiling with -p offand do not enable tracing or hardware counter profiling, the collect command prints a warning message, and collects global sampling data only.
With the –p option, you can collect clock profiling data. The allowed values of option are:
off – Turn off clock profiling.
on – Turn on clock profiling with the default profiling interval of approximately 10 milliseconds.
lo[w] – Turn on clock profiling with the low-resolution profiling interval of approximately 100 milliseconds.
hi[gh] – Turn on clock profiling with the high-resolution profiling interval of approximately 1 millisecond. See Limitations on Clock Profiling for information on enabling high-resolution profiling.
[+]value – Turn on clock profiling and set the profiling interval to value. The default units for value are milliseconds. You can specify value as an integer or a floating-point number. The numeric value can optionally be followed by the suffix m to select millisecond units or u to select microsecond units. The value should be a multiple of the clock resolution. If the value is larger but not a multiple, it is rounded down. If it is smaller, a warning message is printed and it is set to the clock resolution.
Collecting clock profiling data is the default action of the collect command. If you do not collect count data (–c) or data race and deadlock data (–r) then clock profiling data is collected even if you do not specify the –p option.
If you specify –h high or –h low to request the default hardware counters to be set for the processor at high or low-frequency, the default clock profiling is also set to high or low. You can set a different frequency for clock profiling by explicitly setting it with the –p hi or –p low or –p n option.
See Limitations on Clock Profiling for notes about clock-profiling of multithreaded applications on Linux.
Collect hardware counter profiling data. For some hardware, the collect command has defined a default counter set which you can display using collect -h without any arguments. You can also specify particular counters instead of using the default counter set. You can use multiple -h arguments to specify counters.
See Hardware Counter Lists for information about the format of the counters displayed with collect -h.
The allowed values of option used with collect -h are:
Turn off hardware counter profiling. No other options can be specified with -h off.
Turn on hardware counter profiling with the default counter set for the specific hardware system. If the system does not have a default counter set, specifying -h on generates an error.
Turn on hardware counter profiling for the default counter set for the system, and profile at a high rate. If the system does not have a default counter set, specifying -h hi generates an error.
Turn on hardware counter profiling for the default counter set for the system, and profile at a low rate. If the system does not have a default counter set, specifying -h lo generates an error.
Collect hardware counter profiles using one or more specified counters. The maximum number of counters supported (ctr_def through ctr_n_def) is processor-dependent. Run collect -h without any arguments on the current machine to determine the maximum number of hardware counter definitions for profiling and display the full list of available hardware counters and the default counter set.
Memory-related counters are those with type load, store, or load-store as displayed in the counter list when you run the collect -h command without any other command-line arguments. Some such counters are also labeled precise. For precise counters on either SPARC or x86, dataspace and memoryspace data is recorded by default.
Each ctr_def counter definition takes the following form:
ctr[~attr=val]...[~attrN=valN][/reg#],[interval]
The meanings of the counter definition options are as follows:
Processor-specific counter name shown by running the collect -h command without any other command-line arguments. On most systems even if a counter is not listed it can still be specified by a numeric value, either in hexadecimal (0x1234) or decimal. Drivers for older chips do not support numeric values, but drivers for more recent chips do. When a counter is specified numerically, the register number should also be specified. The numeric values to use are found in the chip-specific manufacturer's manuals. The name of the manual is given in the collect -h output. Some counters are only described in proprietary vendor manuals.
Optional one or more attribute options. 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 command-line arguments will also provide a list of attribute names to use for ~attr. The 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). Multiple attributes are concatenated to the counter name. The ~ in front of each attribute name is required.
Hardware register to use for the counter. If 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 see a list of allowable register numbers by running the collect -h command without any other command-line arguments. The / character is required if the register is specified.
The interval is the sampling frequency and can be set to one of the following:
on – The default interval, which you can determine by typing collect -h with no other arguments. Note that the default value for all raw counters is the same, and might not be the most suitable value for a specific counter.
hi – The high-resolution value for the chosen counter, which is approximately ten times shorter than the default.
lo – The low-resolution value for the chosen counter, which is approximately ten times longer than the default.
value – A specific value, which must be a positive integer and can be in decimal or hexadecimal format.
If you omit the interval, the value for -h on is used. However, if you omit the interval you must still supply the comma in front of the omitted interval specification unless you are specifying the last counter in a -h parameter.
For raw counters, the values for hi, lo, and on, are guesses, but the appropriate interval is very hard to guess for any particular program. If you specify on/hi/lo for any raw counters, and the events come in faster than 100/1000/10 per second per thread, respectively, the interval will be throttled down to a more reasonable maximum on Oracle Solaris systems.
-h on
-h lo
-h hi
Enable the default counters with default, low, or
high rates, respectively
-h cycles,,insts,,dcm
-h cycles -h insts -h dcm
Both have the same meaning: three counters: cycles, insts
and dataspace-profiling of D-cache misses (SPARC only)
-h cycles~system=1
Count cycles in both user and system modes
-h 0xc0/0,10000003
On Nehalem, that is the equivalent to
-h inst_retired.any_p/0,10000003
Example 3-2 Invalid Examples of -h Usage
-h cycles -h off Can't use off with any other -h arguments -h cycles,insts Missing comma, and "insts" does not parse as a number for <interval>
If the -h argument specifies the use of hardware counters but hardware counters are in use by root at the time the command is given, the collect command will report an error and no experiment will be run.
If no -h argument is given, no hardware counter profiling data will be collected. An experiment can specify both hardware counter overflow profiling and clock-based profiling. Specifying hardware counter overflow profiling will not disable clock-profiling, even is it is enabled by default.
Collect synchronization wait tracing data. The allowed values of option are:
Turn on synchronization delay tracing and set the threshold value by calibration at runtime
Same as on
Turn off synchronization delay tracing
Turn on synchronization delay tracing with a threshold value of n microseconds; if n is zero, trace all events
Turn on synchronization delay tracing and trace all synchronization events
By default, turn off synchronization delay tracing.
For Java programs, synchronization events for Java monitors in user code are recorded, but not for native synchronization calls within the JVM machine.
On Oracle Solaris, the following functions are traced:
|
On Linux, the following functions are traced:
|
Collect heap tracing data. The allowed values of option are:
Turn on tracing of memory allocation requests
Turn off tracing of memory allocation requests
Heap tracing is turned off by default.
Heap-tracing events are recorded for any native calls and calls to mmap are treated as memory allocations.
Heap profiling is not supported for Java programs. Specifying it is treated as an error.
Note that heap tracing might produce very large experiments. Such experiments are very slow to load and browse.
Collect I/O trace data. The allowed values of option are:
Turn on tracing of I/O operations
Turn off tracing of I/O operations
I/O tracing is not performed by default. I/O tracing might produce very large experiments and such experiments are very slow to load and browse.
Record count data, for Oracle Solaris systems only.
The allowed values of option are:
Turn on count data.
Turn on simulated count data, based on the assumption that every instruction was executed exactly once.
Turn off count data.
By default, turn off collection of count data. Count data cannot be collected with any other type of data.
For count data and simulated count data, the executable and any shared objects that are instrumented and statically linked are counted. For count data, but not simulated count data, dynamically loaded shared objects are also instrumented and counted.
On Oracle Solaris, no special compilation is needed although the count option is incompatible with compile flags -p, -pg, -qp, -xpg, and –-xlinkopt.
On Linux, the executable must be compiled with the -annotate=yes flag in order to collect count data.
On Oracle Linux 5 instability of the runtime linker audit interface (also called rtld-audit or LD_AUDIT) might prevent collection of count data.
Specify a directory for count data instrumentation. This option is available only on Oracle Solaris systems, and is meaningful only when the –c option is also specified.
Specify a library to be excluded from count data instrumentation, whether the library is linked into the executable or loaded with dlopen(). This option is available only on Oracle Solaris systems, and is meaningful only when the –c option is also specified. You can specify multiple –N options.
Record sample packets periodically. The allowed values of option are:
Turn off periodic sampling.
Turn on periodic sampling with the default sampling interval (1 second).
Turn on periodic sampling with a sampling interval of n in seconds; n must be positive.
By default, periodic sampling at 1 second intervals is enabled.
If no data specification arguments are supplied, clock profiling is performed using the default resolution.
If clock profiling is explicitly disabled, and neither hardware counter overflow profiling nor any kind of tracing is enabled, collect displays a warning that no function-level data is being collected, then executes the target and record global data.
Collect data for data race detection or deadlock detection for the Thread Analyzer.
The allowed values of option are:
Collect data for detecting data races.
Collect data for detecting deadlocks and potential deadlocks.
Collect data for detecting data races, deadlocks, and potential deadlocks. Can also be specified as race,deadlock.
Turn off data collection for data races, deadlocks, and potential deadlocks.
Collect data for detecting data races (same as race).
If an unrecoverable error is detected, terminate the target process.
If an unrecoverable error is detected, terminate the target process with a core dump.
If an unrecoverable error is detected, allow the process to continue.
By default, turn off collection of all Thread Analyzer data. The terminate, abort, and continue options can be added to any data-collection options, and govern the behavior when an unrecoverable error occurs, such as a real (not potential) deadlock. The default behavior is terminate.
Thread Analyzer data cannot be collected with any tracing data, but can be collected in conjunction with clock- or hardware counter profiling data. Thread Analyzer data significantly slows down the execution of the target, and profiles might not be meaningful as applied to the user code.
Thread Analyzer experiments can be examined with either analyzer or with tha. Thread Analyzer (tha) displays a simplified list of default data views, but is otherwise identical.
Before you enable data-race detection, you must instrument executables either at compile time, or by invoking a post- processor. If the target is not instrumented, and none of the shared objects on its library list is instrumented, a warning is displayed, but the experiment is run. Other Thread Analyzer data do not require instrumentation.
For more information about the collect -r command and Thread Analyzer, see the Oracle Solaris Studio 12.4: Thread Analyzer User’s Guide and the tha(1) man page.
Specify collection of an MPI experiment. The target of the collect command must be the mpirun command, and its options must be separated from the target programs to be run by the mpirun command by a ‐‐ option. (Always use the ‐‐ option with the mpirun command so that you can collect an experiment by prepending the collect command and its option to the mpirun command line.) The experiment is named as usual and is referred to as the founder experiment. Its directory contains subexperiments for each of the MPI processes, named by rank.
The allowed values of option are:
Turn on collection of an MPI experiment, assuming the MPI version named. The recognized versions of MPI are printed when you type collect with no arguments, or in response to an unrecognized version specified with -M.
Turn off collection of an MPI experiment.
By default, collection of an MPI experiment is turned off. When collection of an MPI experiment is turned on, the default setting for the –m option is changed to on.
The supported versions of MPI are printed when you type the collect -h command with no additional options, or if you specify an unrecognized version with the –M option.
The allowed values of option are:
Turn on MPI tracing information.
Turn off MPI tracing information.
MPI tracing is turned off by default unless the –M option is enabled, in which case MPI tracing is turned on by default. Normally, MPI experiments are collected with the –M option, and no user control of MPI tracing is needed. If you want to collect an MPI experiment but not collect MPI tracing data, use the explicit options –M MPI-version –m off.
See MPI Tracing Data for more information about the MPI functions whose calls are traced and the metrics that are computed from the tracing data.