Collecting Data Using the dbx collector Subcommands

This section shows how to run the Collector from dbx, and then explains each of the subcommands that you can use with the collector command within dbx.

To Run the Collector From dbx:

1. Load your program into dbx by typing the following command.

   % dbx program

2. Use the collector command to enable data collection, select the data types, and set any optional parameters.

   (dbx) collector subcommand

   To get a listing of available collector subcommands, type:

   (dbx) help collector

   You must use one collector command for each subcommand.

3. Set up any dbx options you wish to use and run the program.

   If a subcommand is incorrectly given, a warning message is printed and the subcommand is ignored. A complete listing of the collector subcommands follows.

Data Collection Subcommands

The following subcommands control the types of data that are collected by the Collector. They are ignored with a warning if an experiment is active.

profile option

Controls the collection of clock-based profiling data. The allowed values for option are:

• on– Enables clock-based profiling with the default profiling interval of 10 ms.

• off– Disables clock-based profiling.

• timer interval– Sets the profiling interval. The allowed values of interval are

  • on– Use the default profiling interval of approximately 10 milliseconds.

  • lo[w]– Use the low-resolution profiling interval of approximately 100 milliseconds.

  • hi[gh]– Use the high-resolution profiling interval of approximately 1 millisecond. See Limitations on Clock-Based Profiling for information on enabling high-resolution profiling.

  • value– 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 than the clock resolution but not a multiple it is rounded down. If the value is smaller than the clock resolution it is set to the clock resolution. In both cases a warning message is printed.

    The default setting is approximately 10 milliseconds.

    The Collector collects clock-based profiling data by default, unless the collection of hardware-counter overflow profiling data is turned on using the hwprofile subcommand.

hwprofile option

Controls the collection of hardware counter overflow profiling data. If you attempt to enable hardware counter overflow profiling on systems that do not support it, dbx returns a warning message and the command is ignored. The allowed values for option are:

• on– Turns on hardware counter overflow profiling. The default action is to collect data for the cycles counter at the normal overflow value.

• off– Turns off hardware counter overflow profiling.

• list– Returns a list of available counters. See Hardware Counter Lists for a description of the list. If your system does not support hardware counter overflow profiling, dbx returns a warning message.

• counter counter_definition... [, counter_definition ]– 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 ]

  Selects the hardware counter name, and sets its overflow value to interval; optionally selects additional hardware counter names and sets their overflow values to the specified intervals. The overflow value can be 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.

    If you specify more than one counter, they must use different registers. If they do not, a warning message is printed and the command is ignored.

    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 PC of the instruction that caused the counter overflow. If the search is successful, the PC and the effective address that was referenced are stored in the event data packet.

    The Collector does not collect hardware counter overflow profiling data by default. If hardware-counter overflow profiling is enabled and a profile command has not been given, clock-based profiling is turned off.

    See also Limitations on Hardware Counter Overflow Profiling.

synctrace option

Controls the collection of synchronization wait tracing data. The allowed values for option are

• on– Enable synchronization wait tracing with the default threshold.

• off– Disable synchronization wait tracing.

• threshold value– Sets the threshold for the minimum synchronization delay. The allowed values for value are:

  • all– Use a zero threshold. This option forces all synchronization events to be recorded.

  • calibrate– Set the threshold value by calibration at runtime. (Equivalent to on.)

  • off– Turn off synchronization wait tracing.

  • on– Use the default threshold, which is to set the value by calibration at runtime. (Equivalent to calibrate.)

  • number– Set the threshold to number, given as a positive integer in microseconds. If value is 0, all events are traced.

    By default, the Collector does not collect synchronization wait tracing data.

heaptrace option

Controls the collection of heap tracing data. The allowed values for option are

• on– Enables heap tracing.

• off– Disables heap tracing.

By default, the Collector does not collect heap tracing data.

mpitrace option

Controls the collection of MPI tracing data. The allowed values for option are

• on– Enables tracing of MPI calls.

• off– Disables tracing of MPI calls.

By default, the Collector does not collect MPI tracing data.

tha 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 Thread Analyzer, see the Sun Studio 12: Thread Analyzer User’s Guide and the tha.1 man page.

sample option

Controls the sampling mode. The allowed values for option are:

• periodic– Enables periodic sampling.

• manual– Disables periodic sampling. Manual sampling remains enabled.

• period value– Sets the sampling interval to value, given in seconds.

By default, periodic sampling is enabled, with a sampling interval value of 1 second.

dbxsample { on | off }

Controls the recording of samples when dbx stops the target process. The meanings of the keywords are as follows:

• on– A sample is recorded each time dbx stops the target process.

• off– Samples are not recorded when dbx stops the target process.

By default, samples are recorded when dbx stops the target process.

Experiment Control Subcommands

disable

Disables data collection. If a process is running and collecting data, it terminates the experiment and disables data collection. If a process is running and data collection is disabled, it is ignored with a warning. If no process is running, it disables data collection for subsequent runs.

enable

Enables data collection. If a process is running but data collection is disabled, it enables data collection and starts a new experiment. If a process is running and data collection is enabled, it is ignored with a warning. If no process is running, it enables data collection for subsequent runs.

You can enable and disable data collection as many times as you like during the execution of any process. Each time you enable data collection, a new experiment is created.

pause

Suspends the collection of data, but leaves the experiment open. Sample points are not recorded while the Collector is paused. A sample is generated prior to a pause, and another sample is generated immediately following a resume. This subcommand is ignored if data collection is already paused.

resume

Resumes data collection after a pause has been issued. This subcommand is ignored if data is being collected.

sample record name

Record a sample packet with the label name. The label is displayed in the Event tab of the Performance Analyzer.

Output Subcommands

The following subcommands define storage options for the experiment. They are ignored with a warning if an experiment is active.

archive mode

Set the mode for archiving the experiment. The allowed values for mode are

• on– normal archiving of load objects

• off– no archiving of load objects

• copy– copy load objects into experiment in addition to normal archiving

If you intend to move the experiment to a different machine, or read it from another machine, you should enable the copying of load objects. If an experiment is active, the command is ignored with a warning. This command does not copy source files or object files into the experiment.

limit value

Limit the amount of profiling data recorded to value megabytes. The limit applies to the sum of the amounts of clock-based profiling data, hardware counter overflow profiling data, and synchronization wait tracing data, but not to sample points. The limit is only approximate, and can be exceeded.

When the limit is reached, no more profiling data is recorded but the experiment remains open and sample points continue to be recorded.

The default limit on the amount of data recorded is 2000 Mbytes. This limit was chosen because the Performance Analyzer cannot process experiments that contain more than 2 Gbytes of data. To remove the limit, set value to unlimited or none.

store option

Governs where the experiment is stored. This command is ignored with a warning if an experiment is active. The allowed values for option are:

• directory directory-name– Sets the directory where the experiment and any experiment group is stored. This subcommand is ignored with a warning if the directory does not exist.

• experiment experiment-name– Sets the name of the experiment. If the experiment name does not end in .er, the subcommand is ignored with a warning. See Where the Data Is Stored for more information on experiment names and how the Collector handles them.

• group group-name– Sets the name of the experiment group. If the group name does not end in .erg, the subcommand is ignored with a warning. If the group already exists, the experiment is added to the group. If the directory name has been set using the store directory subcommand and the group name is not an absolute path, the group name is prefixed with the directory name.

Information Subcommands

show

Shows the current setting of every Collector control.

status

Reports on the status of any open experiment.