Product SiteDocumentation Site

Performance Co-Pilot™ Programmer's Guide

Edition 3

Maintained by 
The Performance Co-Pilot Development Team



Legal Notice


Permission is granted to copy, distribute, and/or modify this document under the terms of the Creative Commons Attribution-Share Alike, Version 3.0 or any later version published by the Creative Commons Corp. A copy of the license is available at

Legal Notice


Silicon Graphics, SGI and the SGI logo are registered trademarks and Performance Co-Pilot is a trademark of Silicon Graphics, Inc.
Red Hat and the Shadowman logo are trademarks of Red Hat, Inc., registered in the United States and other countries.
Cisco is a registered trademark of Cisco Systems, Inc. Linux is a registered trademark of Linus Torvalds, used with permission. UNIX is a registered trademark of The Open Group.
About This Guide
1. What This Guide Contains
2. Audience for This Guide
3. Related Resources
4. Man Pages
5. Web Site
6. Conventions
7. Reader Comments
1. Programming Performance Co-Pilot
1.1. PCP Architecture
1.1.1. Distributed Collection
1.1.2. Name Space
1.1.3. Distributed PMNS
1.1.4. Retrospective Sources of Performance Metrics
1.2. Overview of Component Software
1.2.1. Application and Agent Development
1.3. PMDA Development
1.3.1. Overview
1.3.2. Building a PMDA
1.4. Client Development and PMAPI
1.5. Library Reentrancy and Threaded Applications
2. Writing a PMDA
2.1. Implementing a PMDA
2.2. PMDA Architecture
2.2.1. Overview
2.2.2. DSO PMDA
2.2.3. Daemon PMDA
2.2.4. Caching PMDA
2.3. Domains, Metrics, and Instances
2.3.1. Overview
2.3.2. Domains
2.3.3. Metrics
2.3.4. Instances
2.4. Other Issues
2.4.1. Extracting the Information
2.4.2. Latency and Threads of Control
2.4.3. Name Space
2.4.4. PMDA Help Text
2.4.5. Management of Evolution within a PMDA
2.5. PMDA Interface
2.5.1. Overview
2.5.2. PMDA Structures
2.6. Initializing a PMDA
2.6.1. Overview
2.6.2. Common Initialization
2.6.3. Daemon Initialization
2.7. Testing and Debugging a PMDA
2.7.1. Overview
2.7.2. Debugging Information
2.7.3. dbpmda Debug Utility
2.8. Integration of a PMDA
2.8.1. Installing a PMDA
2.8.2. Upgrading a PMNS to Include Metrics from a New PMDA
2.8.3. Removing a PMDA
2.8.4. Configuring PCP Tools
3. PMAPI--The Performance Metrics API
3.1. Naming and Identifying Performance Metrics
3.2. Performance Metric Instances
3.3. Current PMAPI Context
3.4. Performance Metric Descriptions
3.5. Performance Metrics Values
3.6. Performance Event Metrics
3.6.1. Event Monitor Considerations
3.6.2. Event Collector Considerations
3.7. PMAPI Programming Style and Interaction
3.7.1. Variable Length Argument and Results Lists
3.7.2. Python Specific Issues
3.7.3. PMAPI Error Handling
3.8. PMAPI Procedural Interface
3.8.1. PMAPI Name Space Services
3.8.2. PMAPI Metrics Description Services
3.8.3. PMAPI Instance Domain Services
3.8.4. PMAPI Context Services
3.8.5. PMAPI Timezone Services
3.8.6. PMAPI Metrics Services
3.8.7. PMAPI Fetchgroup Services
3.8.8. PMAPI Record-Mode Services
3.8.9. PMAPI Archive-Specific Services
3.8.10. PMAPI Time Control Services
3.8.11. PMAPI Ancillary Support Services
3.9. PMAPI Programming Issues and Examples
3.9.1. Symbolic Association between a Metric's Name and Value
3.9.2. Initializing New Metrics
3.9.3. Iterative Processing of Values
3.9.4. Accommodating Program Evolution
3.9.5. Handling PMAPI Errors
3.9.6. Compiling and Linking PMAPI Applications
4. Instrumenting Applications
4.1. Application and Performance Co-Pilot Relationship
4.2. Performance Instrumentation and Sampling
4.3. MMV PMDA Design
4.4. Memory Mapped Values API
4.4.1. Starting and Stopping Instrumentation
4.4.2. Getting a Handle on Mapped Values
4.4.3. Updating Mapped Values
4.4.4. Elapsed Time Measures
4.5. Performance Instrumentation and Tracing
4.6. Trace PMDA Design
4.6.1. Application Interaction
4.6.2. Sampling Techniques
4.6.3. Configuring the Trace PMDA
4.7. Trace API
4.7.1. Transactions
4.7.2. Point Tracing
4.7.3. Observations and Counters
4.7.4. Configuring the Trace Library
A. Acronyms