Product SiteDocumentation Site

  • pcp-programmers-guide

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.

Table of Contents

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

List of Examples

2.1. Simple PMDA as a DSO
2.2. Simple PMDA as a Daemon
2.3. __pmID_int Structure
2.4. pmdaMetric Structure
2.5. Trivial PMDA
2.6. Effect of Semantics on a Metric
2.7. pmdaInstid Structure
2.8. pmdaIndom Structure
2.9. __pmInDom_int Structure
2.10. Simple PMDA
2.11. pmns File for the Simple PMDA
2.12. Alternate pmns File for the Simple PMDA
2.13. Dynamic metrics pmns File for the Simple PMDA
2.14. Help Text for the Simple PMDA
2.15. Setting Values
2.16. Request Handling Callbacks in the Trivial PMDA
2.17. Request Handling Callbacks in the Simple PMDA
2.18. simple.numfetch Metric
2.19. simple.color Metric
2.20. simple.time Metric
2.21. Metric
2.22. simple_store in the Simple PMDA
2.23. simple.color and PM_ERR_INST Errors
2.24. PM_ERR_PMID Errors
2.26. pmdaInterface Structure Header
2.27. pmdaInterface Structure, Latest Version
2.28. pmdaExt Stucture
2.29. Initialization in the Trivial PMDA
2.30. Initialization in the Simple PMDA
2.31. main in the Simple PMDA
2.32. simple.numfetch in the Simple PMDA
2.33. Install Script for the Trivial PMDA
2.34. Changing Variable Assignments
3.1. Metrics Sharing the Same Instance Domain
3.2. pmDesc Structure
3.3. pmUnits and pmDesc Structures
3.4. pmValueBlock and pmValue Structures
3.5. pmValueBlock Structure
3.6. pmValueSet Structure
3.7. pmResult Structure
3.8. pmEventArray and pmEventRecord Structures
3.9. pmEventParameter Structure
3.10. Unpacking Event Records from an Event Metric pmValueSet
3.11. Dumping Values in Temporal Sequence
3.12. Replaying Interpolated Metrics
3.13. PMAPI Metrics Services
3.14. pmRecordHost Structure
3.15. pmLogLabel Structure
3.16. pmAtomValue Structure
3.17. Using pmPrintValue to Print Values
3.18. pmMetricSpec Structure
3.19. C Code Produced by pmgenmap Input
3.20. Initializing Metric Specifications
3.21. Iterative Processing
3.22. Adding a Metric
3.23. PMAPI Error Handling
4.1. Memory Mapped Value Instance Structures
4.2. Memory Mapped Value Metrics Structures
4.3. Memory Mapped Value Handles
4.4. Memory Mapped Value Updates
4.5. Memory Mapped Value Reports
4.6. Rolling-Window Sampling Technique