.\"--- @(#)template.sh 1.14 90/12/06 SMI; '\" tep .\" %\&Z%%\&M% %\&I% %\&E% SMI; from _source_ .hw time-stamp .TH COLLECTOR 1 "00/03/27" .SH NAME collector \- subcommands of dbx used for performance data collection .SH SYNOPSIS .B dbx .SH AVAILABILITY .LP Available with the Sun WorkShop compilers for C, C++, Fortran 77, Fortran 90, and Assembler. .SH DESCRIPTION .LP The term \f3collector\fP is used to describe the data collection features in \f3dbx\fP or the WorkShop debugger and the runtime support for those features in \f3libcollector.so\fP. .LP The Sun WorkShop Sampling Collector can record a variety of different performance data, and convert each of them into metrics of performance computed against functions, callers and callees of any function, and against source and disassembly representations of the target program. It also records global data with periodic or manual sampling .LP Programs that will be targets for the collector may be compiled with any level of optimization, but must use dynamic linking. If a program is statically linked, the debugger will report an error when you attempt to run the program for data collection. .SH "DATA COLLECTED" .SS "Program-based metrics .TP 5 .B "Clock-based Profiling" Clock-based profiling can run at normal frequency (10 ms.), hi-res frequency (1 ms.), or a custom frequency, specified in milliseconds. For hi-res profiling, the operating system on the machine must be running with a high resolution clock routine, which can be done by putting the line: .in +5 set hires_tick=1 .in -5 in the file \f2/etc/system\fP and rebooting. Hi-res profiles will record ten times as much data for a given run as normal profiles. Attempting to set hi-res profiling on a machine whose operating system does not support it will post an error, and will revert to the highest-resolution supported. Similarly, a custom setting that is not a multiple of the resolution supported by the system will be rounded to the nearest multiple of that resolution, and a warning message given. .sp Profiling will produce data to support the following metrics: .in +5 .nf User CPU Time Total LWP Time System CPU Time System Wait Time Text Page Fault Time Data Page Fault Time .fi .in -5 For MP experiments, all of the times are summed across all LWPs in the process. Total time will add up to the wall-clock time, multiplied by the average number of LWPs in the process. Each record will contain a timestamp, and the thread and LWP id's at the time of the clock tick. .TP 5 .B "Synchronization Delay Tracing" .sp Synchronization delay tracing will record all calls to the various thread synchronization routines where the real-time delay in the call exceeds a specified threshold. Each record contains a timestamp, the thread id and the LWP id at the time the request is initiated. (Synchronization requests from a thread may be initiated on one LWP, but complete on another.) .sp Synchronization delay will produce data to support the following metrics: .in +5 .nf Sync. Delay Events Sync. Wait Time .fi .in -5 .TP 5 .B "Hardware-counter-overflow Profiling" HW-counter-overflow profiling will record the callstack of each LWP at the time the HW counter for the CPU on which it is running overflows. The data also includes a timestamp, and the thread and LWP id's. HW-counter-overflow profiling can be done on Solaris 8 for SPARC (UltraSPARC III machines only) or on Intel (Pentium II and beyond) On other machines, attempt to set HW counter overflow profiling will generate an error. .sp HW-counter-overflow profiling will produce data to support the following metric: .in +5 .nf Counts .fi .in -5 .LP .SS "Sampling and Global Data" Sampling refers to the process of generating markers along the time line of execution, and allowing the processing of data for just part of the run. At each sample point, execution statistics, and, if specified, address space data, are recorded. All of the data recorded at sample points is global to the program, and does not map to function-level metrics. .TP 5 .B "Sampling" Sampling may be either periodic or manual. If periodic, data will be captured at the specified frequency. If manual, a sample is terminated, and a new one begun when the manual sample button on the collector GUI is pressed. .sp In either mode, a sample is terminated and the next one begun whenever the target process stops at a breakpoint, including the internal breakpoints set by dbx. The data recorded at each sample consists of of microstate accounting information from the kernel, along with various other statistics maintained within the kernel. .TP 5 .B "Address Space Data" Address space data consists of page referenced and modified bits for each segment of the target's address space. .SH "DBX COMMANDS" The commands accepted by .B dbx to support performance data collection are: .TP 14 .B "collector { enable|enable_once|disable }" Enable or disable data collection. If the mode is \f3enable\fP, data will be collected for the current run and all subsequent runs. If it is \f3enable_once\fP, data will be collected for the current run, and the mode will be reset to \f3disable\fP when the run ends. If the mode is \f3disable\fP, no performance data will be collected. .TP 14 .B "collector profile { on|off }" Enable or disable collection of profiling data. Default is enabled. .TP 14 .B "collector profile timer " Set the profiling timer interval to , given in milliseconds. Default is 10 ms. .TP 14 .B "collector address_space { on|off }" Enable or disable collecting address space (page reference and modified information) data. Default is off. .TP 14 .B "collector synctrace { on|off }" Enable or disable collecting of synchronization tracing data. Default is off. .TP 14 .B "collector synctrace threshold " Set the threshold for synchronization delay tracing according to the given . .br = "calibrate" means use a calibrated threshold, determined at runtime. .br = means use a threshold of , given in microseconds. .br Setting to "0", means trace all events. .br The default setting is "calibrate". .TP 14 .B "collector hwprofile { on|off }" Enable or disable HW-counter-overflow profiling. On systems whose HW or OS does not support HE-counter-overflow profiling, an error will be returned on attempting to enable it. .TP 14 .B "collector hwprofile list" Return a list of available counters by name, with two numeric settings, one for a normal interval, and one for a higher-resolution interval. .TP 14 .B "collector hwprofile counter " Set the HW counter profiling to the event with the given , and an overflow interval given by . The default choice for is "cycles", at the normal-profiling interval. .TP 14 .B "collector status" Report on the status of any opened experiment. .TP 14 .B "collector show" Show the current settings of all collector control variables. .TP 14 .B "collector close" Close the current experiment. .TP 14 .B "collector quit" Terminate data collection for the current run. .TP 14 .B "collector sample { periodic|manual }" Set the sampling mode to either periodic, or to manual. .TP 14 .B "collector sample period " Set the sampling frequency to , given in seconds. .TP 14 .B "collector store directory " Set the collector directory to . .TP 14 .B "collector store filename " Set the output experiment filename to . .TP 14 .B "help collector" Prompt the user about the various collector commands available. .SH "Attaching to and Collecting Data from a Multithreaded Application" .LP The collector will allow attaching to a multithreaded executable, and collecting performance data from it. .LP If you want to collect thread synchronization delay data, you must have started the executable with the library libcollector.so preloaded, so that the collector's wrapper around the real synchronization routines is referenced, rather than the real routines themselves. To do so, you should: .in +.3i .nf setenv LD_PRELOAD $DIST/WS6/lib/libcollector.so (csh) .br \ \ \ \ \ \ \ \ or .br LD_PRELOAD=$DIST/WS6/lib/libcollector.so; export LD_PRELOAD (sh or ksh) .in -.3i .sp For SPARC-v9 executables, you should use: .in +.3i .nf setenv LD_PRELOAD $DIST/WS6/lib/v9/libcollector.so (csh) .br \ \ \ \ \ \ \ \ or .br LD_PRELOAD=$DIST/WS6/lib/v9/libcollector.so; export LD_PRELOAD (sh or ksh) .sp .in -.3i .fi where $DIST is the directory that contains the installed distribution of the tools (normally, /opt/SUNWspro ). If you are only collecting clock- or HW-counter-overflow profiling data, you need not preload the collector library, although you may do so. .LP Note that you would normally remove the LD_PRELOAD setting after the run, to avoid having it in effect for all other programs started from the same shell. .LP After the executable has been started, you should determine its PID, and attach dbx to it. At that point, you can enable data collection. .LP If you had started the executable from dbx without enabling data collection, you may pause the target from dbx at any time, and then enable data collection. .SH "SEE ALSO" .BR dbx(1), .BR analyzer(1), .BR er_print(1), .BR er_export(1), .BR er_cp(1), .BR er_mv(1), .BR er_rm(1), and .IR "Analyzing Program Performance With Sun WorkShop".