Data Collection Options (Sun Studio 12 Update 1: Performance Analyzer)

Sun Studio 12 Update 1: Performance Analyzer

Data Collection Options

These options control the types of data that are collected. See What 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-based profiling with the default profiling interval of approximately 10 milliseconds. The default is turned off by the -h option but not by any of the other data collection options.

If you explicitly disable clock-based profiling, and do not enable tracing or hardware counter overflow profiling, the collect command prints a warning message, and collects global data only.

`-p` `option`

Collect clock-based profiling data. The allowed values of option are:

off– Turn off clock-based profiling.
on– Turn on clock-based profiling with the default profiling interval of approximately 10 milliseconds.
lo[w]– Turn on clock-based profiling with the low-resolution profiling interval of approximately 100 milliseconds.
hi[gh]– Turn on clock-based profiling with the high-resolution profiling interval of approximately 1 millisecond. See Limitations on Clock-Based Profiling for information on enabling high-resolution profiling.
[+]value– Turn on clock-based 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 it 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.

On SPARC platforms, any value can be prepended with a + sign to enable clock-based dataspace profiling, as is done for hardware counter profiling.

Collecting clock-based profiling data is the default action of the collect command.

`-h` `counter_definition_1` `...[,counter_definition_n]`

Collect hardware counter overflow profiling data. The number of counter definitions is processor-dependent.

This option is now available on systems running the Linux operating system if you have installed the perfctr patch, which you can download from http://user.it.uu.se/~mikpe/linux/perfctr/2.6/ . Instructions for installation are contained within the tar file. The user-level libperfctr.so libraries are searched for using the value of the LD_LIBRARY_PATH environment variable, then in /usr/local/lib, /usr/lib, and /lib for the 32–bit versions, or /usr/local/lib64, /usr/lib64, and /lib64 for the 64–bit versions.

To obtain a list of available counters, type collect with no arguments in a terminal window. A description of the counter list is given in the section Hardware Counter Lists. On most systems, even if a counter is not listed, you can still specify it by a numeric value, either in hexadecimal or decimal.

A counter definition can take one of the following forms, depending on whether the processor supports attributes for hardware counters.

[+]counter_name[/ register_number][,interval ]

[+]counter_name[~ attribute_1=value_1]...[~attribute_n =value_n][/ register_number][,interval ]

The processor-specific counter_name can be one of the following:

An aliased counter name
A raw name
A numeric value in either decimal or hexadecimal

If you specify more than one counter, they must use different registers. If they do not use different registers, the collect command prints an error message and exits.

If the hardware counter counts events that relate to memory access, you can prefix the counter name with a + sign to turn on searching for the true program counter address (PC) of the instruction that caused the counter overflow. This backtracking works on SPARC processors, and only with counters of type load , store , or load-store. If the search is successful, the virtual PC, the physical PC, and the effective address that was referenced are stored in the event data packet.

On some processors, attribute options can be associated with a hardware counter. If a processor supports attribute options, then running the collect command with no arguments lists the counter definitions including the attribute names. You can specify attribute values in decimal or hexadecimal format.

The interval (overflow value) is the number of events or cycles counted at which the hardware counter overflows and the overflow event is recorded. The interval can be set to one of the following:

on, or a null string– The default overflow value, which you can determine by typing collect with no arguments.
hi[gh]– The high-resolution value for the chosen counter, which is approximately ten times shorter than the default overflow value. The abbreviation h is also supported for compatibility with previous software releases.
lo[w]– The low-resolution value for the chosen counter, which is approximately ten times longer than the default overflow value.
interval– A specific overflow value, which must be a positive integer and can be in decimal or hexadecimal format.

The default is the normal threshold, which is predefined for each counter and which appears in the counter list. See also Limitations on Hardware Counter Overflow Profiling.

If you use the -h option without explicitly specifying a-p option, clock-based profiling is turned off. To collect both hardware counter data and clock-based data, you must specify both a -h option and a -p option.

`-s` `option`

Collect synchronization wait tracing data. The allowed values of option are:

all– Enable synchronization wait tracing with a zero threshold. This option forces all synchronization events to be recorded.
calibrate– Enable synchronization wait tracing and set the threshold value by calibration at runtime. (Equivalent to on.)
off– Disable synchronization wait tracing.
on– Enable synchronization wait tracing with the default threshold, which is to set the value by calibration at runtime. (Equivalent to calibrate.)
value– Set the threshold to value, given as a positive integer in microseconds.

Synchronization wait tracing data is not recorded for Java programs; specifying it is treated as an error.

`-H` `option`

Collect heap tracing data. The allowed values of option are:

on– Turn on tracing of heap allocation and deallocation requests.
off– Turn off heap tracing.

Heap tracing is turned off by default. Heap tracing is not supported for Java programs; specifying it is treated as an error.

`-M` `option`

Specify collection of an MPI experiment. The target of the collect command should be the mpirun command, and its options should 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:

MPI-version-Turn on collection of an MPI experiment, assuming the specified MPI version.
off-Turn off collection of an MPI experiment.

By default, turn off collection of an MPI experiment. When 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 command with no options, or if you specify an unrecognized version with the -M option.

`-m` `option`

Collect MPI tracing data. The allowed values of option are:

on– Turn on MPI tracing information.
off– 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.

`-S` `option`

Record sample packets periodically. The allowed values of option are:

off– Turn off periodic sampling.
on– Turn on periodic sampling with the default sampling interval of 1 second.
value– Turn on periodic sampling and set the sampling interval to value. The interval value must be positive, and is given in seconds.

By default, periodic sampling at 1 second intervals is enabled.

`-c` `option`

Record count data, for SPARC processors only.

Note –

This feature requires you to install the Binary Interface Tool (BIT), which is part of the Add-on Cool Tools for OpenSPARC, available at http://cooltools.sunsource.net/. BIT is a tool for measuring performance or test suite coverage of SPARC binaries.

The allowed values of option are

on– Turn on collection of function and instruction count data. Count data and simulated count data are recorded for the executable and for any shared objects that are instrumented and that the executable statically links with, provided that those executables and shared objects were compiled with the -xbinopt=prepare option. Any other shared objects that are statically linked but not compiled with the -xbinopt=prepare option are not included in the data. Any shared objects that are dynamically opened are not included in the simulated count data. The data is viewed in the Instruction-Frequency tab in Performance Analyzer, or with the er_print ifreq command.
off‐ Turn off collection of count data.
static– Generates an experiment with the assumption that every instruction in the target executable and any statically linked shared objects was executed exactly once. As with the -c on option, the -c static option requires that the executables and shared objects are compiled with the -xbinopt=prepare flag.

By default, turn off collection of count data. Count data cannot be collected with any other type of data.

`-I` `directory`

Specify a directory for bit() instrumentation. This option is available only on SPARC-based systems, and is meaningful only when the -c option is also specified.

`-N` `library_name`

Specify a library to be excluded from bit() instrumentation, whether the library is linked into the executable or loaded with dlopen()(). This option is available only on SPARC-based systems, and is meaningful only when the -c option is also specified. You can specify multiple -N options.

`-r` `option`

Collect data for data race detection or deadlock detection for the Thread Analyzer. The allowed values are:

on- Turn on thread analyzer data-race-detection data
off– Turn off thread analyzer data
all– Turn on all thread analyzer data
race- Turn on thread analyzer data-race-detection data
deadlock– Collect deadlock and potential-deadlock data
dtN– Turn on specific thread analyzer data types, as named by the dt* parameters

For more information about the collect -r command and Thread Analyzer, see the Sun Studio 12: Thread Analyzer User’s Guide and the tha.1 man page.