.\"--- @(#)template.sh 1.14 98/03/26 SMI; '\" tep .\" %\&Z%%\&M% %\&I% %\&E% SMI; from _source_ .TH ANALYZER 1 "00/03/27" .SH NAME analyzer \- GUI interface for analyzing a performance experiment .SH SYNOPSIS .B analyzer \ [ .I -s ] [ .I experiment ] .SH AVAILABILITY .LP Available with the Sun WorkShop compilers for C, C++, Fortran 77, Fortran 90, and Assembler. .SH DESCRIPTION .IX "_1st_index_term_" "_2nd_index_term_" "_format_of_1st_" "_format_of_2nd_" .LP The .B Analyzer is a graphical data analysis tool that helps analyze performance data that is collected using the .B Collector from the .B Sun Workshop Debugging window, or by enabling the collector under .B dbx . During the execution of a process with the collector enabled, it gathers performance information to create an experiment. The Analyzer reads in such an experiment, analyzes the data, and displays that data in a graphical display. .LP To activate the Analyzer, you can type .in +.5i .B analyzer [ \f2experiment\fP ] .in -.5i .LP on the command line, or click the Analyzer button on the tool bar in either the main Sun WorkShop window or in the Collector window. If the experiment is not specified on the command line, the analyzer will show a popup of available experiments to allow you to choose. .LP Only one experiment may be specified on the command line; the Experiment Menu may be used to add additional experiments, in which case the data from all the experiments will be aggregated together, and the sample selection mechanism will be disabled. You will only be able to see all the data from all the experiments. .LP The Analyzer supports Help on all of its button menus and pop-up windows. .LP The Analyzer accepts an optional \f2-s \fP flag, defining the session to which it belongs. Analyzers in different sessions will not share an edit window. Analyzers in the same session will. .SS "Analyzer Main Window" .LP The main analyzer main window normally shows the Function list. The option menu immediately below the main menu may be used to select between the Function List, the Overview Window, the Address-space Window, or the Execution statistics Window. The rest of the main window changes depending on which display is chosen. .TP 5 .B "The Function List" When the analyzer is invoked on an experiment, it will read the experiment data, and present a function list, with metrics for the various functions shown. Metrics may be either exclusive or inclusive. Exclusive metrics represent usage within the function itself, and were formerly called "Histogram" data. Inclusive metrics represent usage within the function and all the functions it called, and were formerly called "Cumulative" data. The list of available metrics for each kind of data collected is described in the collector(1) man page. .sp The metrics initially shown are a default set, based on the data collected. For callstack profiling, the default set consist of inclusive and exclusive User CPU time. For thread synchronization delay tracing, the default set consists of inclusive synchronization wait count and inclusive synchronization time. For hardware counter overflow profiling data, the default set consists of inclusive and exclusive event counts. If more than one type of data had been collected, the default metrics for each type are shown. .sp The Analyzer supports data display at the function or load object level (it no longer supports an object module representation); selection is made using the radio buttons in the center of the function list header. The user can control which metrics are shown, and the order in which they appear, by clicking on the "Metrics..." button at the top of the function list. When invoked, a panel showing all of the available metrics is brought up. Each metric has two check boxes, one for the value, and one for the percentage (where appropriate). The name of the object can not be turned off. In addition, there is a set of radio buttons to control which metric is used to sort the list. .sp Time metrics are shown as seconds, presented to millisecond precision. Percentages are shown to a precision of 0.1 %. If a metric value is precisely zero, its time and percentage is shown as "0." If the value is not exactly zero, but is smaller than the precision, its value will be shown as "0.000" and its percentage as "0.0". Count metrics are shown as an integer count. .sp The order of metrics shown will be left to right, matching the top to bottom list in the metric selection panel. To change the function list to use a different order, the user may click the left mouse button on the label for any metric, and drag it up or down in the list. When the ordering, selection or sorting are changed, and the "OK" or "Apply" button is hit, the function list will be updated. .sp At the lower right of the function list, three buttons are shown. The rightmost button, "Callers-Callees...", will invoke the new Callers-Callees window. The middle button, "Source...", will show a listing of the source file containing the selected function, annotated with performance data. The leftmost one, "Disassembly..." will invoke a disassembly listing of the source file containing the selected function, annotated with performance data. .sp The lower left portion of the function list contains a progress bar that is updated during time-consuming operations in the analyzer. It is presents an estimate of the percentage of work for the operation that is completed. To the left of it is a button labeled "Select Filters...", which will invoke the filtering panel described below. .TP 5 .B "The Overview Window" The overview window shows the samples recorded, and allows the user to select a subset of samples to be used for computing performance data. See "Sample Selection", below. .TP 5 .B "The Execution Statistics Window" The Execution Statistics window shows totals for various system statistics summed over the selected samples. .TP 5 .B "The Address Space Window" The Address Space Window shows the referenced and modified information for the various pages in the target. It can show data only if address-space data was selected during the recording of the experiment. If such data was not recorded, the address space window will report that fact. .SS "Analyzer Auxiliary Windows" .TP 5 .B "The Callers-Callees Window" The Callers-Callees screen is invoked from the button labeled "Callers-Callees..." at the bottom of the function list. When invoked, it will show the selected function in the center of the screen, with callers of that function in a panel above, and callees of that function in a panel below. .sp In addition to showing the metric values for each function, it also shows "Attributed" metrics. For the center function, the attributed metric represents the exclusive metric for that function, while for the callees below, it represents the proportion of the callee's metric that is attributable to calls from the center function. The sum of attributed metrics for the callees and the center function should add up to the inclusive metric for the center function. .sp For the callers above, the attributed metrics represent the inclusive metric value for the center function, as attributed up the callstack to its callers. The sum of the attributed metrics for all callers should also add up to the inclusive metric for the center function. .sp The metrics shown in the Callers-Callees window, and the sorting used, can be changed by invoking the "Metrics..." button at the bottom left of the Callers-Callees window. Sorting may only be done by attributed metrics. The Callers-Callees window only works when the function list is set to show functions, not when it is set to show load objects. When the function list is set to show load objects, the Callers-Callees window will not show any data. .sp Clicking on a different function in the function list, or on an entry in the current caller or callee list will update the Callers-Callees window to center it on the selected function. .TP 5 .B "The Source Display" The source display shows the source of the selected function, if available, annotated with performance metrics for each source line, and any compiler commentary shown interleaved with the source to which it pertains. In the rare case where the same source file is used to compile more than one object file, the source display shows the performance data for the object file containing the selected function. .TP 5 .B "The Disassembly Display" The disassembly display shows a disassembly listing of the selected function, annotated with performance metrics for each instruction. If the source of the function is available, it will be shown interleaved with the disassembly listing; if any compiler commentary pertains to the source file, it, too, will be interleaved in the disassembly display. In the rare case where the same source file is used to compiler more than one object file, the disassembly display shows the disassembly and performance data for the object file containing the selected function. .TP 5 .B "The Summary Metrics Screen" The Summary Metrics Screen is invoked from the Function List's "View" menu item called "Show Details". It will show all the recorded metrics for the selected function, both as values and percentages. Selecting a different function from either the function list, or the Callers-Callees screen will update the Summary Metrics screen. If the function list is set to show load objects, the Summary Metrics screen will show the data for the selected load object. .SS "Filtering Data: Sample, Thread, LWP and Load-Object Selectivity" .LP Normally, data is shown for all samples, all threads and all LWPs. However, a subset of data may also be selected. Any such selection can be made from the Select Filters Panel, invoked from a button at the bottom of the main display. In addition, filtering based on the load object from which the functions appear may be done through the Select Load Objects Included panel, invoked through the View Menu. The Select Filters Panel consists of three sections, each with a text field used to enter a selection. The three sections are for filtering samples, threads and LWPs. All three filters may be applied simultaneously, although care should be taken in interpreting data when simultaneously filtering by threads and LWPs. .LP Similarly, the function list usually shows functions from all load objects referenced during the run. It can be filtered to only show functions from a subset of load objects. .TP 5 .B "Sample Selection" Samples are numbered from 1\-\f2N\fP, and any set of samples may be selected. The selection consists of a single sample number, a range of sample numbers, or a comma-separated list of sample numbers or ranges. .TP 5 .B "Thread Selection" Threads are numbered from 1\-\f2N\fP, and any set of threads may be selected. The selection consists of a single thread number, a range of thread numbers, or a comma-separated list of thread numbers or ranges. Profile data for threads only covers that part of the run where the thread was actually scheduled on an LWP. .TP 5 .B "LWP Selection" LWPs are numbered from 1\-\f2N\fP, and any set of LWPs may be selected. The selection consists of a single LWP number, a range of LWP numbers, or a comma-separated list of LWP numbers or ranges. If thread synchronization data is recorded, the LWP reported is the LWP at entry to a synchronization event, which may or may not be the same LWP at exit from the synchronization event. .TP 5 .B "Load Object Selection" The term Load Object refers to the executable (a.out) or any shared objects it links with or loads. The displays may be restricted to show only functions from a subset of load objects. To do so, invoke the "Select Load Objects Included ..." item on the View menu. It will bring up a panel with controls to allow you to set or clear load objects from the list. .SS "Generating Mapfiles and Function Reordering" .LP In addition to analyzing the data, the Analyzer also provides a function reordering capability. Based on the experiment, the Analyzer can generate a mapfile that when used with the static linker (ld) to relink the application creates an executable with a smaller working set size, better I-cache behavior, or both. .SS "Other Functions" .LP The Analyzer also provides the ability to add additional experiments to the current set, or drop experiments from the set. If the current set contains more than one experiment, sample selection is disabled: all samples from all experiments are shown. .SH "SEE ALSO" .BR dbx(1), .BR collector(1), .BR er_export(1), .BR er_print(1), .BR er_cp(1), .BR er_mv(1), .BR er_rm(1), .BR workshop(1), and .br .IR "Analyzing Program Performance With Sun WorkShop".