Product SiteDocumentation Site

Chapter 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
This chapter describes the Performance Metrics Application Programming Interface (PMAPI) provided with Performance Co-Pilot (PCP).
The PMAPI is a set of functions and data structure definitions that allow client applications to access performance data from one or more Performance Metrics Collection Daemons (PMCDs) or from PCP archive logs. The PCP utilities are all written using the PMAPI.
The most common use of PCP includes running performance monitoring utilities on a workstation (the monitoring system) while performance data is retrieved from one or more remote collector systems by a number of PCP processes. These processes execute on both the monitoring system and the collector systems. The collector systems are typically servers, and are the targets for the performance investigations.
In the development of the PMAPI the most important question has been, “How easily and quickly will this API enable the user to build new performance tools, or exploit existing tools for newly available performance metrics?” The PMAPI and the standard tools that use the PMAPI have enjoyed a symbiotic evolution throughout the development of PCP.
It will be convenient to differentiate between code that uses the PMAPI and code that implements the services of the PMAPI. The former will be termed “above the PMAPI” and the latter “below the PMAPI.”

3.1. Naming and Identifying Performance Metrics

Across all of the supported performance metric domains, there are a large number of performance metrics. Each metric has its own description, format, and semantics. PCP presents a uniform interface to these metrics above the PMAPI, independent of the source of the underlying metric data. For example, the performance metric hinv.physmem has a single 32-bit unsigned integer value, representing the number of megabytes of physical memory in the system, while the performance metric has one 32-bit unsigned integer value per disk spindle, representing the cumulative count of I/O operations involving each associated disk spindle. These concepts are described in greater detail in Section 2.3, “Domains, Metrics, and Instances”.
For brevity and efficiency, internally PCP avoids using names for performance metrics, and instead uses an identification scheme that unambiguously associates a single integer with each known performance metric. This integer is known as a Performance Metric Identifier, or PMID. For functions using the PMAPI, a PMID is defined and manipulated with the typedef pmID.
Below the PMAPI, the integer value of the PMID has an internal structure that reflects the details of the PMCD and PMDA architecture, as described in Section 2.3.3, “Metrics”.
Above the PMAPI, a Performance Metrics Name Space (PMNS) is used to provide a hierarchic classification of external metric names, and a one-to-one mapping of external names to internal PMIDs. A more detailed description of the PMNS can be found in the Performance Co-Pilot User's and Administrator's Guide.
The default PMNS comes from the performance metrics source, either a PMCD process or a PCP archive. This PMNS always reflects the available metrics from the performance metrics source