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 may 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/perfctr-2.6.15.tar.gz .
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:
-
A well-known (aliased) counter name
-
A raw (internal) name, as used by cputrack(1). If the counter can use either event register, the event register to be used can be specified by appending /0 or /1 to the internal name.
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. Some counters can count on either register.
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.
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 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 monitors.
-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
Collect MPI tracing data. The allowed values of option are:
-
on– Turn on tracing of MPI calls.
-
off– Turn off tracing of MPI calls.
MPI tracing is turned off by default.
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 Sun Studio 12, 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. Data is recorded for the executable and for any shared objects that the executable statically links with, provided that those executables and shared objects were compiled with the -xbinopt=prepare flag. Any other shared objects that are statically linked but not compiled with the -xbinopt=prepare flag are not included in the data. Likewise, any shared objects that are dynamically opened are not included in the data. The data is viewed in the Instruction-Frequency tab in Performance Analyzer, or with the er_print ifreq command.
-
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.
-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.
- © 2010, Oracle Corporation and/or its affiliates