Product SiteDocumentation Site

Chapter 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
This chapter constitutes a programmer's guide to writing a Performance Metrics Domain Agent (PMDA) for Performance Co-Pilot (PCP).
The presentation assumes the developer is using the standard PCP libpcp_pmda library, as documented in the PMDA(3) and associated man pages.

2.1. Implementing a PMDA

The job of a PMDA is to gather performance data and report them to the Performance Metrics Collection Daemon (PMCD) in response to requests from PCP monitoring tools routed to the PMDA via PMCD.
An important requirement for any PMDA is that it have low latency response to requests from PMCD. Either the PMDA must use a quick access method and a single thread of control, or it must have asynchronous refresh and two threads of control: one for communicating with PMCD, the other for updating the performance data.
The PMDA is typically acting as a gateway between the target domain (that is, the performance instrumentation in an application program or service) and the PCP framework. The PMDA may extract the information using one of a number of possible export options that include a shared memory segment or mmap file; a sequential log file (where the PMDA parses the tail of the log file to extract the information); a snapshot file (the PMDA rereads the file as required); or application-specific communication services (IPC).

Note

The choice of export methodology is typically determined by the source of the instrumentation (the target domain) rather than by the PMDA.
Procedure 2.1, “Creating a PMDA” describes the suggested steps for designing and implementing a PMDA:

Procedure 2.1. Creating a PMDA

  1. Determine how to extract the metrics from the target domain.
  2. Select an appropriate architecture for the PMDA (daemon or DSO, IPC, pthreads or single threaded).
  3. Define the metrics and instances that the PMDA will support.
  4. Implement the functionality to extract the metric values.
  5. Assign Performance Metric Identifiers (PMIDs) for the metrics, along with names for the metrics in the Performance Metrics Name Space (PMNS). These concepts will be further expanded in Section 2.3, “Domains, Metrics, and Instances”
  6. Specify the help file and control data structures for metrics and instances that are required by the standard PMDA implementation library functions.
  7. Write code to supply the metrics and associated information to PMCD.
  8. Implement any PMDA-specific callbacks, and PMDA initialization functions.
  9. Exercise and test the PMDA with the purpose-built PMDA debugger; see the dbpmda(1) man page.
  10. Install and connect the PMDA to a running PMCD process; see the pmcd(1) man page.
  11. Configure or develop tools to use the new metrics. For examples of visualization tools, see the pmchart(1) and pmgadgets(1) man pages. For examples of text-based tools, see the pminfo(1) and pmval(1) man pages.
  12. Where appropriate, define pmie rule templates suitable for alerting or notification systems. For more information, see the pmie(1) and pmieconf(1) man pages.
  13. Where appropriate, define pmlogger configuration templates suitable for creating PCP archives containing the new metrics. For more information, see the pmlogconf(1) and pmlogger(1) man pages.