HP PAK Performance Analysis Tools User's Guide HP 9000 Computers B3476-90017 Printed in USA May 1997 © Copyright 1997 Hewlett-Packard Company
Legal Notices The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. © Copyright 1979, 1980, 1983, 1985-1990 Regents of the University of California. This software is based in part on the Fourth Berkeley Software Distribution under license from the Regents of the University of California. © Copyright 1985-1986, 1988 Massachussetts Institute of Technology. X Window System is a trademark of the Massachussetts Institute of Technology.
iv
Contents 1. Overview of HP PAK Tools Introduction to HP PAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Using Puma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Invoking Puma's Graphical User Interface . . . . . . . . . . . . . . . . . . . . . .3 For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Invoking Puma's Command-Line Interface . . . . . . . . . . . . . . . . . . . .
Contents Direct Collapse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Conservative Collapse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Full Collapse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3. Puma Command Quick Reference Data Collection Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Data Analysis Commands . . . . . . . . . . . . . . . . . . . . . . .
Preface HP PAK Performance Analysis Tools User's Guide introduces the tools in the HP PAK Programmer's Analysis Kit. These include Puma, which analyzes program performance; TTV, which analyzes trace files produced by an instrumented thread library; and XPS, which displays the relative use of system resources by executing processes. Comments We welcome your comments on this manual. Please send electronic mail to editor@ch.hp.
Technical Summary HP PAK 7.10 is an upgrade of HP PAK 7.0. The following list summarizes the differences HP PAK 7.10 and HP PAK 7.0. • XPS is unchanged in this release. • A new tool, TTV, has been added to HP PAK. TTV reads, synthesizes, and analyzes the trace files produced by the instrumented thread library (libpthread_tr.sl or libpthread_tr.a), and presents the resulting information in graphical form.
Documentation Conventions This manual uses the following symbolic conventions. literal values Bold monospaced words or characters in command formats and command descriptions represent commands or keywords that you must use literally. Path names are also in bold. user-supplied values Italic words or characters in command formats and command descriptions represent values that you must supply. [] Square brackets enclose optional items in formats and command descriptions.
Printing History B3476-90017 B3476-90016 B3476-90011 May 1997 July 1996 June 1995 Version 7.10 Version 7.0 Version 6.0 The printing date and part number at the top indicate the current edition. The printing date changes when a new edition is printed. (Minor corrections and updates which are incorporated at reprint do not cause the date to change.) The part number changes when extensive technical changes are incorporated. We may issue a technical addendum or release notes to supplement this manual.
1 Overview of HP PAK Tools This chapter provides a brief overview of the HP PAK tools: Puma, TTV, and XPS. It describes how to start up the tools, and explains where to find more help.
Overview of HP PAK Tools Introduction to HP PAK Introduction to HP PAK HP PAK consists of three tools that help you analyze the performance of your applications: • Puma monitors the program counter, the call/return stack, and other performance statistics of executing programs. It saves the results in a data file. You can then view the data file in a variety of graphical formats.
Overview of HP PAK Tools Using Puma Using Puma Puma is a tool that collects performance data from the system as a program runs. It saves the collected data to a file. You can then use Puma to analyze the information in the data file, or to play back the program's stack traces and thread states for close review. Puma has three user interfaces: • The graphical user interface, based on the conventions of OSF/Motif, is useful for interactive collection and analysis of program performance data.
Overview of HP PAK Tools Using Puma Figure 1-1 The Main Puma Window The Puma main window is your starting point for all Puma activities. For example: ❏ The Collect Performance Data button brings up windows that guide you through the process of collecting performance data. ❏ The Collected Performance Data (Files) list box displays Puma data files that exist in the current working directory.
Overview of HP PAK Tools Using Puma • Select Call Tree Analysis to display a given performance metric relative to the libraries and routines that executed during the sample set. • Select Playback Thread States to step through the stack trace of multi-threaded programs (on systems that support kernel-threaded applications). ❏ The Messages box displays any run-time messages generated by Puma.
Overview of HP PAK Tools Using Puma Invoking Puma's Command-Line Interface To invoke Puma's command-line interface, enter the puma -text command in a shell. The puma> prompt will be displayed. For example: $ puma -text puma> To exit Puma, enter exit or quit. For More Information See Chapter 3, “Puma Command Quick Reference,” for more information on Puma commands and on the Puma command-line interface. See Chapter 2, “Puma Concepts,” for more information on how Puma collects data and generates statistics.
Overview of HP PAK Tools Using Puma Using Puma's Shell Script Interface You can invoke Puma from a shell or shell script to execute a single command. Enter the command puma and the name of the desired command as an option, that is, precede the command name with a hyphen. You can also supply arguments to the command option.
Overview of HP PAK Tools Using TTV Using TTV The TTV (Thread Trace Visualizer) is a utility that reads the trace files produced by the instrumented thread library (libpthread_tr.sl or libpthread_tr.a). TTV provides a graphical format for the presentation and analysis of the data (see Figure 1-2). Figure 1-2 TTV Display To produce thread traces, you need to link your application to the instrumented thread library.
Overview of HP PAK Tools Using TTV Alternatively, you can start ttv without a list of trace files. You can then load trace files from the File menu in the grapical user interface. You can also invoke TTV from the Tools menu in the main Puma window. The data from your trace files are presented in the two graphs in the TTV main window. You can change the scope and content of the graphs in many ways. For More Information Online help is available from TTV's Help menu or from the ttv(1) man page.
Overview of HP PAK Tools Using XPS Using XPS XPS provides a graphical display of CPU and I/O usage by the processes that are currently executing. The display is updated periodically. To run XPS, enter xps at the shell prompt. An XPS screen, like the one in Figure 1-3, appears. Scroll up and down in the XPS display using standard OSF/Motif tools (scroll bars or paging keys). To end XPS's monitoring at any time, press q or Ctrl-c anywhere in the XPS display.
Overview of HP PAK Tools Using XPS Figure 1-3 XPS Display Chapter 1 11
Overview of HP PAK Tools Using XPS 12 Chapter 1
2 Puma Concepts This chapter is a general description of how Puma gathers data and generates statistics.
Puma Concepts Procedure Relationships Procedure Relationships The terms that describe the relationship of a given procedure to other procedures in the same program are: parent A procedure that directly calls the given procedure. ancestor A procedure that calls the given procedure, either directly or through another procedure or procedures; all parents are also ancestors. child A procedure called directly by the given procedure.
Puma Concepts Procedure Relationships Figure 2-1 vanderbilt Procedure Relationships To Puma, the relationships among procedures are dynamic, reflecting the possibility that sometimes x may call y and later y may call x. Puma analyzes your program as it is seen at run time; Puma does not base the analysis on the lexical structure of the program as seen at compile time.
Puma Concepts How Puma Gathers Data How Puma Gathers Data To collect performance data, Puma performs the following steps at each sampling interval: 1. Stop the program. 2. Take a sample from the program's image. 3. Store the sample in a memory buffer. 4. Release the program, allowing it to resume execution. A sample is a unit of data gathered by Puma. A sample contains stack trace information and statistical information about the current state of the program.
Puma Concepts How Puma Gathers Data Figure 2-2 Active Procedures Statistical Information Puma records statistical information concerning the program's resource use, including: • time spent in user space ("user cycles") • time spent in system space ("system cycles") • major page faults • minor page faults • socket messages sent • socket messages received • signals received • files open • page swaps • characters (bytes) of I/O Data Files Puma stores the samples it collects in a data file.
Puma Concepts How Puma Gathers Data command-line mode, Puma either creates or overwrites DataSet1.puma. Use the -dat option to create a data file with a different name. When invoked in graphical mode, Puma displays icons for the data files that reside in the directory where it is executing, and that have the filename extension .puma. You can load data files with other filename extensions manually from within Puma.
Puma Concepts How Puma Generates Statistics How Puma Generates Statistics The information that Puma produces from a data file consists of statistical summaries for the run of the program. For example, Puma can report the percentage of samples in which each procedure was active (that is, how often control was in the procedure itself or in any of its descendants). Puma can present statistical information in a variety of ways.
Puma Concepts How Puma Generates Procedure Names How Puma Generates Procedure Names In the Call Tree Analysis windows, you can direct Puma to display performance metrics by procedure (routine). This section describes the naming conventions that Puma uses when displaying procedure names. When Puma can determine a procedure's name, it displays the name in case-correct format.
Puma Concepts How Puma Analyzes Recursive Procedures How Puma Analyzes Recursive Procedures When procedures in a program are recursive, the call structure at run time (the dynamic call structure) can be more complex than the order of procedure calls that is apparent before run time (the static call structure). The Recursion Collapsing area of the Call Tree Analysis window allows you to specify how you want Puma to collapse its reporting of recursive routines.
Puma Concepts How Puma Analyzes Recursive Procedures (This analysis uses the raw count for clarity; the percentage or parent percentage would not reflect a strictly accurate picture, as the percentages are approximations. The in-only raw counts of the nested procedures add up to the in-or-under raw count of 6 for main.) This analysis, although correct, does not properly summarize the program's behavior.
Puma Concepts How Puma Analyzes Recursive Procedures Puma Recursion Collapsing Options There are four degrees of recursion collapsing to choose from in a Puma analysis. They are, in order of increasing presence of recursion collapsing: No collapse Performs no recursion collapsing. Direct collapse Performs recursion collapsing for direct recursion (that is, if a routine calls itself directly).
Puma Concepts How Puma Analyzes Recursive Procedures stub built at the recursive call to a, since the transformation from main a b a to main a loses the only instance of b. However, it would have a recursive stub at the recursive call to b, since the collapsing of main a b a b to main a b loses an instance of a, but leaves another one. As another example, the call chain main a b c b a d c would not have any recursive stubs using Conservative collapse.
Puma Concepts How Puma Analyzes Recursive Procedures lines have 0 as their direct value and 1 as their indirect value, because those nodes were reached only after traversing recursive stubs. When a node, such as a at Level 2, is reached directly and then again in the same stack trace through a recursive stub, the direct arrival counts; that is why these lines have a direct value of 1.
Puma Concepts How Puma Analyzes Recursive Procedures 26 Chapter 2
3 Puma Command Quick Reference This chapter provides a quick summary of the commands available in the Puma command-line and shell script interfaces. .
Puma Command Quick Reference Data Collection Commands Data Collection Commands mo[nitor] [monitor_options] Perform data collection, using the given options. sh[ow] mo[nitor] Show the current default data-collection options. se[t] mo[nitor] monitor_options Modify the default data-collection options. pr[ocesses] List the processes currently executing on the machine. Data Analysis Commands an[alyze] [analyze_options] Generate an analysis, using the given options.
Puma Command Quick Reference Miscellaneous Commands Miscellaneous Commands e[xit] Exit from Puma command interface. he[lp] [command] Provide general help information (when no argument) or help information on a Puma command (when command is supplied). ma[n] command Provide a full description of the specified Puma command. q[uit] Exit from Puma command interface. sh[ow] al[l] [>filename] Show defaults for data-collection and analysis commands; optionally write them to filename.
Puma Command Quick Reference Miscellaneous Commands 30 Chapter 3
4 XPS Overview, Options, and Commands This chapter contains a brief description of XPS, including information on its options and commands.
XPS Overview, Options, and Commands XPS Overview XPS Overview Figure 4-1 XPS Display XPS displays process and I/O usage dynamically, using a bar chart interface based on OSF/Motif. For each process that you own, XPS displays a separate bar showing the relative percentage of CPU time being consumed by that process. You can display other user processes and OS server processes individually, with a separate bar for each process.
XPS Overview, Options, and Commands XPS Overview When you invoke the xps command, you will see a display like that shown in Figure 4-1. The Process Name section provides the names of your processes. By default, XPS groups all other user processes under Other Processes and all operating system processes under OS Processes. To expand Other Processes and display the processes individually, use the -p option. To expand OS Processes and display the processes individually, use the -l1 option.
XPS Overview, Options, and Commands XPS Options XPS Options Specify options as a single option or as a list of options separated by spaces. The available options are: -r n Update the display every n seconds. By default, the display is updated every 4 seconds. -p Expand the Other Processes group to show a bar for each process. Other processes are all user processes other than the processes that you own. By default, XPS groups all these processes and displays them with a single bar.
XPS Overview, Options, and Commands XPS Window Commands XPS Window Commands While XPS is running, you can use various keys to move within the window, to get help, and to exit. Table 4-1 shows the definitions for various keys while XPS is running.
XPS Overview, Options, and Commands XPS Window Commands 36 Chapter 4
Glossary Active A state of a procedure. Puma considers a procedure to be active if control is in the procedure itself or in any of its descendants. Data file A file in which Puma stores the data that it collects from a process. Data files are used during analysis and playback. Ancestor A procedure that calls the given procedure, either directly or through another procedure or procedures. Contrast with parent.
Glossary Granularity The degree of detail in which Puma displays analysis data. Data may be shown separately for each routine or library of a program; or data may be aggregated and associated with the top-level caller. The former granularity is called "in-only"; the latter is called "in-or-under." Library As a Puma datacollection option, the term library refers to a dynamically loaded library; that is, a collection of executable routines bound together.
Glossary Percent cutoff A specification that restricts entries in a Puma analysis to procedures consuming more than a certain amount of execution time. By default, the percent cutoff is 0, which, in effect, instructs Puma to include information about every procedure that consumes 0% or more of the execution time (that is, every procedure that occurred in any stacktrace that Puma recorded). Performance statistics A set of metrics that Puma collects from a program run to aid in analyzing performance.
Glossary Recursion collapsing A Puma analysis mechanism for reporting on the recursion of a program. When you request recursion collapsing, Puma may not make a new node in a tree of call chains if it encounters a recursive call (depending on the type of recursion collapsing you specify). Instead Puma creates a recursive stub that represents the recursion and refers to the place higher up the call chain where the same routine occurs.
Index A analysis commands Puma, 28 ancestor of a procedure, 14 C Call Tree Analysis window Puma, 5 child procedure, 14 collecting performance data Puma, 5 command syntax Puma, 28 command-line interface Puma, 6 Conservative collapse Puma, 23 D data collection commands Puma, 28 data files Puma, 5, 17 descendant of a procedure, 14 Direct collapse Puma, 23 E example program, 7 exiting Puma, 3 F Full collapse Puma, 24 H help Puma, 5, 6 TTV, 9 XPS, 10 Index I in-only, 16 in-or-under, 16 instrumented thread lib
Index P Pan/Zoom window Puma, 5 parent procedure, 14 PATH variable, 2 Playback Thread States window Puma, 5 procedure names Puma, 20 procedure relationships, 14 procedures active, 16 procedure names (Puma), 20 unknown, 20 process display XPS, 32 Puma analysis commands, 28 Call Tree Analysis window, 5 collecting performance data, 5 command syntax, 28 command-line interface, 6 Conservative collapse, 23 data collection commands, 28 data files, 5, 17 Direct collapse, 23 exiting, 3 Full collapse, 24 invoking, 3
Index T trace_thread.
