This guide describes how to program Performance Co-Pilot (PCP), a software package of advanced performance management applications for the SGI family of graphical workstations and servers. PCP provides a systems-level suite of tools that cooperate to deliver distributed, integrated performance monitoring and performance management services spanning the hardware platform, the operating system, service layers, user applications, and distributed application architectures.
This guide contains the following chapters:
Chapter 1, “Programming Performance Co-Pilot”, contains a thumbnail sketch of how to program the various PCP components.
Chapter 2, “Writing a PMDA”, describes how to write Performance Metrics Domain Agents (PMDAs) for PCP.
Chapter 3, “PMAPI--The Performance Metrics API”, describes the interface that allows you to design custom performance monitoring tools.
Chapter 4, “Trace PMDA”, provides an introduction to the design of the trace Performance Metrics Domain Agent (PMDA).
Appendix A, “Acronyms”, provides a comprehensive list of the acronyms used in this guide, in the PCP man pages, and in the release notes.
The guide describes the programming interfaces to Performance Co-Pilot (PCP) for the following intended audience:
Performance analysts or system administrators who want to extend or customize performance monitoring tools available with PCP
Developers who need to integrate their applications into the PCP framework
This book is written for those who are competent with the C programming language, the UNIX or the Linux operating systems, and the target domain from which the desired performance metrics are to be extracted. Familiarity with the PCP tool suite is assumed.
The Performance Co-Pilot for IRIX Advanced User's and Administrator's Guide and Performance Co-Pilot for IA-64 Linux User's and Administrator's Guide, which are companion documents to the Performance Co-Pilot Programmer's Guide, are intended for system administrators and performance analysts who are directly using and administering PCP applications.
Additional resources include man pages, release notes (IRIX only), and SGI Web sites.
The operating system man pages provide concise reference information on the use of commands, subroutines, and system resources. There is usually a man page for each PCP command or subroutine. To see a list of all the PCP man pages, enter the following command:
man -k performance
To see a particular man page, supply its name to the man command, for example:
The man pages are divided into the following seven sections:
System calls and error numbers
Demos and games
When referring to man pages, this guide follows a standard convention: the section number in parentheses follows the item. For example, pmda(3) refers to the man page in section 3 for the pmda command.
Release notes provide specific information about the current product release, available online through the relnotes command. Exceptions to the printed and online documentation are found in the release notes. The grelnotes command provides a graphical interface to the release notes of all products installed on your system. For additional information, see the relnotes(1) and grelnotes(1) man pages. Release notes are not available on the Linux operating system.
The following Web sites are accessible to everyone with general Internet access:
You can obtain SGI documentation in the following ways:
See the SGI Technical Publications Library at: http://docs.sgi.com. Various formats are available. This library contains the most recent and most comprehensive set of online books, release notes, man pages, and other information.
If it is installed on your SGI system, you can use InfoSearch, an online tool that provides a more limited set of online books, release notes, and man pages. With an IRIX system, select Help from the Toolchest, and then select InfoSearch. Or you can type infosearch on a command line.
You can also view release notes by typing either grelnotes or relnotes on a command line.
You can also view man pages by typing man title on a command line.
The following conventions are used throughout this document:
This fixed-space font denotes literal items such as commands, files, routines, path names, signals, messages, and programming language structures.
Italic typeface denotes variable entries and words or concepts being defined.
This bold, fixed-space font denotes literal items that the user enters in interactive sessions. (Output is shown in nonbold, fixed-space font.)
Brackets enclose optional portions of a command or directive line.
Ellipses indicate that a preceding element can be repeated.
All capital letters denote environment variables, operator names, directives, defined constants, and macros in C programs.
Parentheses that follow function names surround function arguments or are empty if the function has no arguments; parentheses that follow IRIX commands surround man page section numbers.
If you have comments about the technical accuracy, content, or organization of this document, contact SGI. Be sure to include the title and document number of the manual with your comments. (Online, the document number is located in the front matter of the manual. In printed manuals, the document number is located at the bottom of each page.)
You can contact SGI in any of the following ways:
Send e-mail to the following address:
Use the Feedback option on the Technical Publications Library Web page:
Contact your customer service representative and ask that an incident be filed in the SGI incident tracking system.
Send mail to the following address:
|1600 Amphitheatre Parkway, M/S 535|
|Mountain View, California 94043-1351|
Send a fax to the attention of “Technical Publications” at +1 650 932 0801.
SGI values your comments and will respond to them promptly.