Pcp Documentation Release 5.3.1-1
Total Page:16
File Type:pdf, Size:1020Kb
pcp Documentation Release 5.3.1-1 Performance Co-Pilot Jun 03, 2021 GUIDES 1 Installation 3 1.1 Distribution Packages..........................................3 1.2 Upstream Packages............................................3 2 User’s and Administrator’s Guide5 2.1 What This Guide Contains........................................5 2.2 Audience for This Guide.........................................6 2.3 Related Resources............................................6 2.4 Man Pages................................................6 2.5 Web Site.................................................7 2.6 Conventions...............................................7 2.7 Reader Comments............................................7 3 Programmer’s Guide 9 3.1 What This Guide Contains........................................9 3.2 Audience for This Guide......................................... 10 3.3 Related Resources............................................ 10 3.4 Man Pages................................................ 10 3.5 Web Site................................................. 11 3.6 Conventions............................................... 11 3.7 Reader Comments............................................ 11 4 Scaling Guidelines 13 4.1 Architectures............................................... 13 4.2 Sizing Factors.............................................. 14 4.3 Configuration Options.......................................... 15 4.4 Results and Analysis........................................... 16 4.5 Appendix A............................................... 16 5 Introduction to PCP 17 5.1 Objectives................................................ 18 5.2 Conceptual Foundations......................................... 21 5.3 Overview of Component Software.................................... 26 6 Installing and Configuring Performance Co-Pilot 33 6.1 Product Structure............................................. 34 6.2 Performance Metrics Collection Daemon (PMCD)........................... 34 6.3 Managing Optional PMDAs....................................... 40 6.4 Troubleshooting............................................. 42 7 Common Conventions and Arguments 47 i 7.1 Alternate Metrics Source Options.................................... 48 7.2 General PCP Tool Options........................................ 49 7.3 Time Duration and Control........................................ 50 7.4 PCP Environment Variables....................................... 52 7.5 Running PCP Tools through a Firewall................................. 54 7.6 Transient Problems with Performance Metric Values.......................... 54 8 Monitoring System Performance 57 8.1 The pmstat Command.......................................... 58 8.2 The pmrep Command.......................................... 59 8.3 The pmval Command.......................................... 59 8.4 The pminfo Command.......................................... 61 8.5 The pmstore Command......................................... 65 9 Performance Metrics Inference Engine 67 9.1 Introduction to pmie........................................... 68 9.2 Basic pmie Usage............................................ 70 9.3 Specification Language for pmie..................................... 73 9.4 pmie Examples.............................................. 83 9.5 Developing and Debugging pmie Rules................................. 85 9.6 Caveats and Notes on pmie........................................ 85 9.7 Creating pmie Rules with pmieconf................................... 87 9.8 Management of pmie Processes..................................... 89 10 Archive Logging 93 10.1 Introduction to Archive Logging..................................... 94 10.2 Using Archive Logs with Performance Tools.............................. 96 10.3 Cookbook for Archive Logging..................................... 99 10.4 Other Archive Logging Features and Services.............................. 102 10.5 Archive Logging Troubleshooting.................................... 105 11 Performance Co-Pilot Deployment Strategies 109 11.1 Basic Deployment............................................ 110 11.2 PCP Collector Deployment....................................... 111 11.3 PCP Archive Logger Deployment.................................... 112 11.4 PCP Inference Engine Deployment................................... 113 12 Customizing and Extending PCP Services 117 12.1 PMDA Customization.......................................... 118 12.2 PCP Tool Customization......................................... 120 12.3 PMNS Management........................................... 122 12.4 PMDA Development........................................... 124 12.5 PCP Tool Development......................................... 124 13 Fast, Scalable Time Series Querying - pmseries 125 13.1 Introduction to pmseries......................................... 126 13.2 Timeseries Queries............................................ 127 13.3 Metadata Qualifiers and Metadata Operators.............................. 127 13.4 Time Specification............................................ 128 13.5 Expressions................................................ 129 13.6 Timeseries Options............................................ 132 13.7 PCP Environment............................................ 136 13.8 PCP Grafana Plugin........................................... 137 14 Programming Performance Co-Pilot 139 ii 14.1 PCP Architecture............................................. 140 14.2 Overview of Component Software.................................... 141 14.3 PMDA Development........................................... 142 14.4 Client Development and PMAPI..................................... 144 14.5 Library Reentrancy and Threaded Applications............................. 144 15 Writing A PMDA 145 15.1 Implementing a PMDA.......................................... 146 15.2 PMDA Architecture........................................... 147 15.3 Domains, Metrics, Instances and Labels................................. 150 15.4 Other Issues............................................... 161 15.5 PMDA Interface............................................. 165 15.6 Initializing a PMDA........................................... 173 15.7 Testing and Debugging a PMDA..................................... 177 15.8 Integration of a PMDA.......................................... 178 16 PMAPI–The Performance Metrics API 183 16.1 Naming and Identifying Performance Metrics.............................. 186 16.2 Performance Metric Instances...................................... 186 16.3 Current PMAPI Context......................................... 188 16.4 Performance Metric Descriptions.................................... 188 16.5 Performance Metrics Values....................................... 191 16.6 Performance Event Metrics....................................... 193 16.7 PMAPI Programming Style and Interaction............................... 197 16.8 PMAPI Procedural Interface....................................... 199 16.9 PMAPI Programming Issues and Examples............................... 232 17 Instrumenting Applications 239 17.1 Application and Performance Co-Pilot Relationship.......................... 240 17.2 Performance Instrumentation and Sampling............................... 241 17.3 MMV PMDA Design.......................................... 241 17.4 Memory Mapped Values API...................................... 241 17.5 Performance Instrumentation and Tracing................................ 246 17.6 Trace PMDA Design........................................... 247 17.7 Trace API................................................. 249 iii iv pcp Documentation, Release 5.3.1-1 Performance Co-Pilot (PCP) provides a framework and services to support system-level performance monitoring and management. It presents a unifying abstraction for all of the performance data in a system, and many tools for interro- gating, retrieving and processing that data. PCP is a feature-rich, mature, extensible, cross-platform toolkit supporting both live and retrospective analysis. The distributed PCP architecture makes it especially useful for those seeking centralized monitoring of distributed process- ing. Table of Contents • Installation • User’s and Administrator’s Guide • Programmer’s Guide • Scaling Guidelines • REST API Specification GUIDES 1 pcp Documentation, Release 5.3.1-1 2 GUIDES CHAPTER ONE INSTALLATION 1.1 Distribution Packages Performance Co-Pilot is already included in the most popular distributions (RHEL, Debian, Fedora, SUSE, Ubuntu). These packages can be installed with the distribution package manager. 1.2 Upstream Packages Additionally we build packages of each PCP version for multiple distribution on our custom build infrastructure. These packages are usually more recent than the distribution packages. 1.2.1 Fedora / RHEL / CentOS Create a file /etc/yum.repos.d/performancecopilot.repo with the following content. Note: Replace fedora with centos when using CentOS or RHEL. [performancecopilot] name=Performance Co-Pilot baseurl=https://performancecopilot.jfrog.io/artifactory/pcp-rpm-release/fedora/ ,!$releasever/$basearch enabled=1 gpgcheck=0 gpgkey=https://performancecopilot.jfrog.io/artifactory/pcp-rpm-release/fedora/ ,!$releasever/$basearch/repodata/repomd.xml.key repo_gpgcheck=1 Install PCP using the package manager: $ sudo dnf install pcp-zeroconf 3 pcp Documentation, Release 5.3.1-1 1.2.2 Debian / Ubuntu Run the following commands. Note: Replace