diff options
Diffstat (limited to 'books')
| -rw-r--r-- | books/GNUmakefile | 18 | ||||
| -rw-r--r-- | books/PCP_PG/Book_Info.xml | 15 | ||||
| -rw-r--r-- | books/PCP_PG/GNUmakefile | 61 | ||||
| -rw-r--r-- | books/PCP_PG/pcp-programmers-guide.pdf | bin | 0 -> 958446 bytes | |||
| -rw-r--r-- | books/PCP_PG/pcp-programmers-guide.xml | 5888 | ||||
| -rw-r--r-- | books/PCP_PG/publican.cfg | 5 | ||||
| -rw-r--r-- | books/PCP_TCS/Book_Info.xml | 15 | ||||
| -rw-r--r-- | books/PCP_TCS/GNUmakefile | 61 | ||||
| -rw-r--r-- | books/PCP_TCS/pcp-tutorials-and-case-studies.pdf | bin | 0 -> 142897 bytes | |||
| -rw-r--r-- | books/PCP_TCS/pcp-tutorials-and-case-studies.xml | 334 | ||||
| -rw-r--r-- | books/PCP_TCS/publican.cfg | 5 | ||||
| -rw-r--r-- | books/PCP_UAG/Book_Info.xml | 14 | ||||
| -rw-r--r-- | books/PCP_UAG/GNUmakefile | 61 | ||||
| -rw-r--r-- | books/PCP_UAG/pcp-users-and-administrators-guide.pdf | bin | 0 -> 912142 bytes | |||
| -rw-r--r-- | books/PCP_UAG/pcp-users-and-administrators-guide.xml | 8020 | ||||
| -rw-r--r-- | books/PCP_UAG/publican.cfg | 5 | ||||
| -rw-r--r-- | books/README | 10 |
17 files changed, 14512 insertions, 0 deletions
diff --git a/books/GNUmakefile b/books/GNUmakefile new file mode 100644 index 0000000..fec6f61 --- /dev/null +++ b/books/GNUmakefile @@ -0,0 +1,18 @@ +# +# Copyright (c) 2013 Red Hat. +# + +TOPDIR = .. +include $(TOPDIR)/src/include/builddefs + +SUBDIRS = PCP_UAG PCP_PG PCP_TCS +LSRCFILES = README + +default install: $(SUBDIRS) + $(SUBDIRS_MAKERULE) + +include $(BUILDRULES) + +default_pcp : default + +install_pcp : install diff --git a/books/PCP_PG/Book_Info.xml b/books/PCP_PG/Book_Info.xml new file mode 100644 index 0000000..6a28877 --- /dev/null +++ b/books/PCP_PG/Book_Info.xml @@ -0,0 +1,15 @@ +<?xml version='1.0'?> +<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<bookinfo id="pcp-programmers-guide"> + <title>pcp-programmers-guide</title> + <subtitle>Performance Co-Pilot Programmer's Guide</subtitle> + <edition>3</edition> + <productname>PCP</productname> + <productnumber>3</productnumber> + <pubsnumber>1</pubsnumber> + <xi:include href="Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>--> + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</bookinfo> diff --git a/books/PCP_PG/GNUmakefile b/books/PCP_PG/GNUmakefile new file mode 100644 index 0000000..010c762 --- /dev/null +++ b/books/PCP_PG/GNUmakefile @@ -0,0 +1,61 @@ +TOPDIR = ../.. +include $(TOPDIR)/src/include/builddefs + +IAM = pcp-programmers-guide +XML = $(IAM).xml +PDF = $(IAM).pdf +PUB = Book_Info.xml +CFG = publican.cfg + +LSRCFILES = $(XML) $(PUB) $(CFG) $(PDF) +LDIRDIRT = pdf html en-US +LDIRT = built.* +CWD = $(shell pwd) + +default: build-me + +include $(BUILDRULES) + +ifeq "$(BOOK_TOOLCHAIN)" "publican" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf html en-US + @mkdir -p pdf html en-US/xml + $(LN_S) $(CWD)/$(PUB) en-US/ + $(LN_S) $(CWD)/$(XML) en-US/xml/ + $(LN_S) $(CWD)/$(TOPDIR)/images en-US/xml/figures + $(PUBLICAN) build --langs=en-US --formats=pdf + @# $(PUBLICAN) build --langs=en-US --formats=pdf,html + $(LN_S) $(CWD)/en-US/pdf/*.pdf pdf/$(IAM).pdf +endif + +ifeq "$(BOOK_TOOLCHAIN)" "dblatex" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf figures + $(LN_S) $(CWD)/$(TOPDIR)/images figures + $(DBLATEX) --type=pdf --output-dir=pdf $(XML) +endif + +ifeq "$(BOOK_TOOLCHAIN)" "xmlto" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf html figures + @mkdir -p pdf html + $(LN_S) $(CWD)/$(TOPDIR)/images pdf/figures + $(LN_S) $(CWD)/$(TOPDIR)/images html/figures + $(XMLTO) --with-fop -o pdf pdf $(XML) + $(XMLTO) --with-fop -o html html $(XML) +endif + +ifneq "$(findstring $(BOOK_TOOLCHAIN),publican dblatext xmlto)" "" +build-me: built.$(BOOK_TOOLCHAIN) + @touch built.$(BOOK_TOOLCHAIN) +else +build-me: +endif + +install: default + $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR) + $(INSTALL) -m 644 $(PDF) $(PCP_BOOKS_DIR)/$(PDF) + +default_pcp : default + +install_pcp : install diff --git a/books/PCP_PG/pcp-programmers-guide.pdf b/books/PCP_PG/pcp-programmers-guide.pdf Binary files differnew file mode 100644 index 0000000..1843331 --- /dev/null +++ b/books/PCP_PG/pcp-programmers-guide.pdf diff --git a/books/PCP_PG/pcp-programmers-guide.xml b/books/PCP_PG/pcp-programmers-guide.xml new file mode 100644 index 0000000..53bb7b7 --- /dev/null +++ b/books/PCP_PG/pcp-programmers-guide.xml @@ -0,0 +1,5888 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<book status="final" security="public"><title>Performance Co-Pilot™ Programmer's Guide</title> +<bookinfo><edition>3</edition> + +<othercredit> +<contrib>Maintained by</contrib> +<affiliation> +<orgname>The Performance Co-Pilot Development Team</orgname> +<address> +<email>pcp@mail.performancecopilot.org</email> +<otheraddr> +<ulink url="http://www.performancecopilot.org"/> +<inlinemediaobject><imageobject><imagedata fileref="figures/pcp.svg"/></imageobject></inlinemediaobject> +</otheraddr> +</address> +</affiliation> +</othercredit> + +<copyright> +<year>2000</year> +<year>2013</year> +<holder>Silicon Graphics, Inc.</holder> +</copyright> + +<copyright> +<year>2013</year> +<year>2014</year> +<holder>Red Hat, Inc.</holder> +</copyright> + +<legalnotice> +<title>LICENSE</title> +<para>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 +<ulink url="http://creativecommons.org/licenses/by-sa/3.0/us/"/></para> +</legalnotice> + +<legalnotice> +<title>TRADEMARKS AND ATTRIBUTIONS</title> +<para>Silicon Graphics, SGI and the SGI logo are registered trademarks +and Performance Co-Pilot is a trademark of Silicon Graphics, Inc.</para> +<para>Red Hat and the Shadowman logo are trademarks of Red Hat, Inc., +registered in the United States and other countries.</para> +<para>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.</para> +</legalnotice> + +<revhistory> +<revision><revnumber>007</revnumber><date>September 2013</date><revremark>Revised to include event metrics and the MMV PMDA coverage.</revremark></revision> +<revision><revnumber>006</revnumber><date>August 2013</date><revremark>Revised to support the Performance Co-Pilot 3.8 release.</revremark></revision> +<revision><revnumber>005</revnumber><date>December 2002</date><revremark>Revised to support the Performance Co-Pilot 2.3 release.</revremark></revision> +<revision><revnumber>004</revnumber><date>March 2001</date><revremark>Revised to support the Performance Co-Pilot 2.2 release.</revremark></revision> +<revision><revnumber>003</revnumber><date>July 1999</date><revremark>Revised to support the Performance Co-Pilot 2.1 release.</revremark></revision> +</revhistory> + +</bookinfo> +<toc/> + + +<preface id="id5178752"> + +<title>About This Guide</title> +<para>This guide describes how to program the Performance Co-Pilot (PCP) performance analysis toolkit. +PCP provides a systems-level suite of tools that cooperate to deliver +distributed performance monitoring and performance management services spanning +hardware platforms, operating systems, service layers, database internals, +user applications and distributed architectures.</para> +<para>PCP is an open source, cross-platform software package - customizations, extensions, +source code inspection, and tinkering in general is actively encouraged.</para> +<para>“About This Guide” includes short descriptions of the chapters +in this book, directs you to additional sources of information, and explains +typographical conventions.</para> +<section id="id5178771"> + +<title>What This Guide Contains</title> +<para>This guide contains the following chapters:</para> +<itemizedlist> +<listitem><para><xref linkend="LE21795-PARENT"/>, contains a thumbnail sketch of how to program the various PCP components.</para> +</listitem> +<listitem><para><xref linkend="LE98072-PARENT"/>, describes how to write Performance Metrics Domain Agents (PMDAs) for PCP.</para> +</listitem> +<listitem><para><xref linkend="LE97135-PARENT"/>, describes the interface that allows you to design custom performance monitoring tools.</para> +</listitem> +<listitem><para><xref linkend="LE25915-PARENT"/>, introduces techniques, tools and interfaces to assist with exporting performance data from within applications.</para> +</listitem> +<listitem><para><xref linkend="LE54271-PARENT"/>, provides a comprehensive list of the acronyms used in this guide, in the PCP man pages, and in the release notes.</para> +</listitem></itemizedlist> +</section> +<section id="id5178891"> + +<title>Audience for This Guide</title> +<para>The guide describes the programming interfaces to Performance Co-Pilot (PCP) for the following intended audience:</para> +<itemizedlist> +<listitem><para>Performance analysts or system administrators who want to extend or customize performance monitoring tools available with PCP</para> +</listitem> +<listitem><para>Developers who wish to integrate performance data from within their applications into the PCP framework</para> +</listitem></itemizedlist> +<para>This book is written for those who are competent with the C programming language, the UNIX or the Linux operating systems, and the target domain from which the desired performance metrics are to be extracted. Familiarity with the PCP tool suite is assumed.</para> +</section> +<section id="id5178933"> + +<title>Related Resources</title> +<para>The <citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle> +is a companion document to the <citetitle>Performance Co-Pilot Programmer's Guide</citetitle>, +and is intended for system administrators and performance analysts who are directly +using and administering PCP installations.</para> +<para>The <citetitle>Performance Co-Pilot Tutorials and Case Studies</citetitle> +provides a series of real-world examples of using various PCP tools, and +lessons learned from deploying the toolkit in production environments. +It serves to provide reinforcement of the general concepts discussed in the +other two books with additional case studies, and in some cases very detailed +discussion of specifics of individual tools. +</para> +<para>Additional resources include man pages and the project web site.</para> +</section> +<section id="id5178968"> + +<title>Man Pages</title> +<para>The operating system man pages provide concise reference information on the use of commands, subroutines, and system resources. There is usually a man page for each PCP command or subroutine. To see a list of all the PCP man pages, start from the following command:</para> +<literallayout class="monospaced"><userinput>man PCPIntro</userinput></literallayout> +<para>Each man page usually has a "SEE ALSO" section, linking to other, related entries.</para> +<para>To see a particular man page, supply its name to the <literal>man</literal> command, for example:</para> +<literallayout class="monospaced"><userinput>man pcp</userinput></literallayout> +<para>The man pages are arranged in different sections separating commands, programming interfaces, and so on. +For a complete list of manual sections on a platform enter the command:</para> +<literallayout class="monospaced"><userinput>man man</userinput></literallayout> +<para>When referring to man pages, this guide follows a standard convention: the section number in parentheses follows the item. For example, <command>pminfo(1)</command> refers to the man page in section 1 for the <command>pminfo</command> command.</para> +</section> +<section id="id5179157"> + +<title>Web Site</title> +<para>The following web site is accessible to everyone:</para> +<variablelist condition="sgi_termlength:wide"> +<varlistentry> +<term><emphasis role="bold">URL</emphasis></term><listitem><para><emphasis role="bold">Description</emphasis></para></listitem></varlistentry> +<varlistentry> +<term><ulink url="http://www.performancecopilot.org">http://www.performancecopilot.org</ulink></term> +<listitem><para>PCP is open source software released under +the GNU General Public License (GPL) and GNU Lesser General Public License (LGPL)</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5179276"> + +<title>Conventions</title> +<para>The following conventions are used throughout this document:<variablelist> +<varlistentry> +<term><emphasis role="bold">Convention</emphasis></term><listitem><para><emphasis role="bold">Meaning</emphasis></para></listitem></varlistentry> +<varlistentry> +<term><literal>${PCP_VARIABLE}</literal></term> +<listitem><para>A brace-enclosed all-capital-letters syntax indicates a variable +that has been sourced from the global <filename>/etc/pcp.conf</filename> file. +These special variables indicate parameters that affect all PCP commands, +and are likely to be different between platforms.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><literal>command</literal></term> +<listitem><para>This fixed-space font denotes literal items such as commands, +files, routines, path names, signals, messages, and programming language +structures. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><replaceable>variable</replaceable></term> +<listitem><para>Italic typeface denotes variable entries and words or concepts being +defined.</para> +</listitem></varlistentry> + +<varlistentry> +<term><userinput>user input</userinput></term> +<listitem><para>This bold, fixed-space font denotes literal items that the user enters in interactive sessions. (Output is shown in nonbold, fixed-space font.)</para> +</listitem></varlistentry> + +<varlistentry> +<term>[ ]</term> +<listitem><para>Brackets enclose optional portions of a command or directive line.</para> +</listitem></varlistentry> + +<varlistentry> +<term>...</term> +<listitem><para>Ellipses indicate that a preceding element can be repeated.</para> +</listitem></varlistentry> +<varlistentry> +<term>ALL CAPS</term> +<listitem><para>All capital letters denote environment variables, operator names, directives, defined constants, and macros in C programs.</para> +</listitem></varlistentry> +<varlistentry> +<term>()</term> +<listitem><para>Parentheses that follow function names surround function arguments or are empty if the function has no arguments; parentheses that follow commands surround man page section numbers.</para> +</listitem></varlistentry> +</variablelist></para> + +</section> +<section id="z825546061melby"> + +<title>Reader Comments</title> +<para>If you have comments about the technical accuracy, content, or organization of this document, contact the PCP maintainers using either the email address or the web site listed earlier.</para> +<para>We value your comments and will respond to them promptly.</para> +</section> +</preface> + + +<chapter id="LE21795-PARENT"> + +<title>Programming Performance Co-Pilot</title> +<para><indexterm id="IG313401770"><primary>PCP</primary><secondary>description</secondary></indexterm>Performance Co-Pilot (PCP) provides a systems-level suite of tools that cooperate to deliver distributed, integrated performance management services. PCP is designed for the in-depth analysis and sophisticated control that are needed to understand and manage the hardest performance problems in the most complex systems.</para> +<para>PCP provides unparalleled power to quickly isolate and understand performance behavior, resource utilization, activity levels and performance bottlenecks.</para> +<para>Performance data may be collected and exported from multiple sources, most notably the hardware platform, the operating system kernel, layered services, and end-user applications.</para> +<para><indexterm id="IG313401771"><primary>programming components</primary></indexterm> <indexterm id="IG313401772"><primary>audience</primary></indexterm>There are several ways to extend PCP by programming certain of its components:</para> +<itemizedlist> +<listitem><para><indexterm id="Z963349317sdc"><primary>Performance Metrics Domain Agent </primary><see>PMDA</see></indexterm><indexterm id="IG313401773"><primary>PMDA</primary><secondary>introduction</secondary></indexterm>By writing a Performance Metrics Domain Agent (PMDA) to collect performance metrics from an uncharted performance domain (<xref linkend="LE98072-PARENT"/>)</para> +</listitem> +<listitem><para><indexterm id="Z963349400sdc"><primary>Performance Metrics Application Programming Interface </primary><see>PMAPI</see></indexterm><indexterm id="IG313401774"><primary>PMAPI</primary><secondary>introduction</secondary></indexterm>By creating new analysis or visualization tools using documented functions from the Performance Metrics Application Programming Interface (PMAPI) (<xref linkend="LE97135-PARENT"/>)</para> +</listitem> +<listitem><para><indexterm id="IG313401775"><primary>performance instrumentation</primary></indexterm><indexterm id="IG313401776"><primary>trace facilities</primary></indexterm>By adding performance instrumentation to an application using facilities from PCP libraries, which offer both sampling and event tracing models.</para> +</listitem></itemizedlist> +<para><indexterm id="IG313401777"><primary>customization</primary></indexterm>Finally, the topic of customizing an installation is covered in the chapter on customizing and extending PCP service in the <citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle>.</para> +<section id="id5177140"> + +<title>PCP Architecture</title> +<para><indexterm id="IG313401778"><primary>architecture</primary></indexterm>This section gives a brief overview of PCP architecture. For an explanation of terms and acronyms, refer to <xref linkend="LE54271-PARENT"/>.</para> +<para><indexterm id="IG313401779"><primary>pmchart command</primary></indexterm><indexterm id="IG3134017711"><primary>monitoring tools</primary></indexterm><indexterm id="IG3134017712"><primary>collection tools</primary></indexterm>PCP consists of numerous monitoring and collecting tools. <literal>Monitoring tools</literal> such as <command>pmval</command> and <command>pminfo</command> report on metrics, but have minimal interaction with target systems. <literal>Collection tools</literal>, called PMDAs, extract performance values from target systems, but do not provide user interfaces.</para> +<para>Systems supporting PCP services are broadly classified into two categories:</para> +<variablelist> +<varlistentry> +<term>Collector</term> +<listitem><para>Hosts that have the PMCD and one or more PMDAs running to collect and export performance metrics</para> +</listitem></varlistentry> +<varlistentry> +<term>Monitor</term> +<listitem><para>Hosts that import performance metrics from one or more collector hosts to be consumed by tools to monitor, manage, or record the performance of the collector hosts</para> +</listitem></varlistentry> +</variablelist> +<para>Each PCP enabled host can operate as a collector, or a monitor, or both.</para> +<para><xref linkend="id5177328"/> shows the architecture of PCP. The monitoring tools consume and process performance data using a public interface, the Performance Metrics Application Programming Interface (PMAPI).</para> +<para><indexterm id="IG3134017713"><primary>PMCD</primary><secondary>overview</secondary></indexterm><indexterm id="IG3134017714"><primary>Performance Metrics Collection Daemon </primary><see>PMCD</see></indexterm>Below the PMAPI level is the PMCD process, which acts in a coordinating role, accepting requests from clients, routing requests to one or more PMDAs, aggregating responses from the PMDAs, and responding to the requesting client.</para> +<para>Each performance metric domain (such as the operating system kernel or a database management system) has a well-defined name space for referring to the specific performance metrics it knows how to collect.</para> +<para><figure id="id5177328"><title>PCP Global Process Architecture</title><mediaobject><imageobject><imagedata fileref="figures/local-collector.svg"/></imageobject><textobject><phrase>PCP Global Process Architecture</phrase></textobject></mediaobject></figure></para> +<section id="id5177343"> + +<title>Distributed Collection</title> +<para><indexterm id="IG3134017715"><primary>distributed performance management</primary><secondary>metrics collection</secondary></indexterm><indexterm id="IG3134017716"><primary>Cisco PMDA</primary></indexterm><indexterm id="IG3134017717"><primary>Cluster PMDA</primary></indexterm>The performance metrics collection architecture is distributed, in the sense that any monitoring tool may be executing remotely. However, a PMDA is expected to be running on the operating system for which it is collecting performance measurements; there are some notable PMDAs such as Cisco and Cluster that are exceptions, and collect performance data from remote systems.</para> +<para><indexterm id="IG3134017718"><primary>PMCD</primary><secondary>distributed collection</secondary></indexterm><indexterm id="IG3134017719"><primary>collector hosts</primary></indexterm>As shown in <xref linkend="id5177408"/>, monitoring tools communicate only with PMCD. The PMDAs are controlled by PMCD and respond to requests from the monitoring tools that are forwarded by PMCD to the relevant PMDAs on the collector host.</para> +<para><figure id="id5177408"><title>Process Structure for Distributed Operation</title><mediaobject><imageobject><imagedata fileref="figures/remote-collector.svg"/></imageobject><textobject><phrase>Process Structure for Distributed Operation</phrase></textobject></mediaobject></figure></para> +<para>The host running the monitoring tools does not require any collection tools, including PMCD, since all requests for metrics are sent to the PMCD process on the collector host.</para> +<para><indexterm id="IG3134017720"><primary>PMDA </primary><secondary>man page</secondary></indexterm><indexterm id="IG3134017721"><primary>PMAPI</primary><secondary>man page</secondary></indexterm>The connections between monitoring tools and PMCD processes are managed in <filename>libpcp</filename>, below the PMAPI level; see the <command>PMAPI(3)</command> man page. Connections between PMDAs and PMCD are managed by the PMDA functions; see the <command>PMDA(3)</command> and <command>pmcd(1)</command> man pages. There can be multiple monitor clients and multiple PMDAs on the one host, but there may be only one PMCD process.</para> +</section> +<section id="id5177529"> + +<title>Name Space</title> +<para><indexterm id="IG3134017722"><primary>name space</primary></indexterm><indexterm id="IG3134017723"><primary>Performance Metric Identifier</primary><see>PMID</see></indexterm><indexterm id="IG3134017724"><primary>PMID</primary><secondary>introduction</secondary></indexterm>Each PMDA provides a domain of metrics, whether they be for the operating system, a database manager, a layered service, or an application module. These metrics are referred to by name inside the user interface, and with a numeric Performance Metric Identifier (PMID) within the underlying PMAPI.</para> +<para><indexterm id="IG3134017725"><primary>clusters</primary></indexterm><indexterm id="IG3134017726"><primary>item numbers</primary></indexterm><indexterm id="IG3134017727"><primary>domains</primary><secondary>fields</secondary></indexterm>The PMID consists of three fields: the domain, the cluster, and the item number of the metric. The domain is a unique number assigned to each PMDA. For example, two metrics with the same domain number must be from the same PMDA. The cluster and item numbers allow metrics to be easily organized into groups within the PMDA, and provide a hierarchical taxonomy to guarantee uniqueness within each PMDA.</para> +<para><indexterm id="IG3134017728"><primary>Performance Metrics Name Space</primary><see>PMNS</see></indexterm>The Performance Metrics Name Space (PMNS) describes the exported performance metrics, in particular the mapping from PMID to external name, and vice-versa.</para> +</section> +<section id="id5177616"> + +<title>Distributed PMNS</title> +<para> <indexterm id="IG3134017729"><primary>PMNS</primary><secondary>distributed</secondary></indexterm> Performance metric namespace (PMNS) operations are directed by default to the host or archive that is the source of the desired performance metrics.</para> +<para>In <xref linkend="id5177408"/>, both Performance Metrics Collection Daemon (PMCD) processes would respond to PMNS queries from monitoring tools by referring to their local PMNS. If different PMDAs were installed on the two hosts, then the PMNS used by each PMCD would be different, to reflect variations in available metrics on the two hosts.</para> +<para>Although extremely rarely used, the <command>-n</command> <replaceable>pmnsfile</replaceable> command line option may be used with many PCP monitoring tools to force use of a local PMNS file in preference to the PMNS at the source of the metrics.</para> +</section> +<section id="id5177692"> + +<title>Retrospective Sources of Performance Metrics</title> +<para><indexterm id="IG3134017730"><primary>retrospective analysis</primary></indexterm>The distributed collection architecture described in the previous section is used when PMAPI clients are requesting performance metrics from a real-time or live source.</para> +<para><indexterm id="IG3134017731"><primary>archive logs</primary><secondary>retrospective sources</secondary></indexterm>The PMAPI also supports delivery of performance metrics from a historical source in the form of a PCP archive log. Archive logs are created using the <command>pmlogger</command> utility, and are replayed in an architecture as shown in <xref linkend="id5177742"/>.</para> +<para><figure id="id5177742"><title>Architecture for Retrospective Analysis</title><mediaobject><imageobject><imagedata fileref="figures/retrospective-architecture.svg"/></imageobject><textobject><phrase>Architecture for Retrospective Analysis</phrase></textobject></mediaobject></figure></para> +</section> +</section> +<section id="LE13618-PARENT"> + +<title>Overview of Component Software</title> +<para><indexterm id="IG3134017732"><primary>software</primary></indexterm><indexterm id="IG3134017733"><primary>component software</primary></indexterm>Performance Co-Pilot (PCP) is composed of text-based tools, optional graphical tools, and related commands. Each tool or command is fully documented by a man page. These man pages are named after the tools or commands they describe, and are accessible through the <command>man</command> command. For example, to see the <command>pminfo(1)</command> man page for the <command>pminfo</command> command, enter this command:<literallayout class="monospaced"><userinput>man pminfo</userinput></literallayout></para> +<para>A list of PCP developer tools and commands, grouped by functionality, is provided in the following section.</para> +<section id="id5177879"> + +<title>Application and Agent Development</title> +<para><indexterm id="ITch01-114"><primary>application programs</primary></indexterm><indexterm id="IG3134017734"><primary>PCP</primary><secondary>tool summaries</secondary></indexterm>The following PCP tools aid the development of new programs to consume performance data, and new agents to export performance data within the PCP framework:</para> +<variablelist> +<varlistentry> +<term><command>chkhelp</command></term> +<listitem><para><indexterm id="IG3134017735"><primary>chkhelp tool</primary></indexterm>Checks the consistency of performance metrics help database files.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>dbpmda</command></term> +<listitem><para><indexterm id="IG3134017736"><primary/></indexterm>Allows PMDA behavior to be exercised and tested. It is an interactive debugger for PMDAs.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>mmv</command></term> +<listitem><para><indexterm id="IG3134017742nat"><primary>mmv library</primary><see>MMV</see></indexterm>Is used to instrument applications using Memory Mapped Values (MMV). These are values that are communicated with <command>pmcd</command> instantly, and very efficiently, using a shared memory mapping. It is a program instrumentation library.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>newhelp</command></term> +<listitem><para><indexterm id="IG3134017737"><primary>newhelp tool</primary></indexterm>Generates the database files for one or more source files of PCP help text.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmapi</command></term> +<listitem><para><indexterm id="IG3134017738"><primary>pmclient tool</primary><secondary>brief description</secondary></indexterm><indexterm id="IG3134017739"><primary>PMAPI</primary></indexterm><indexterm id="IG3134017740"><primary>Performance Metrics Application Programming Interface </primary><see>PMAPI</see></indexterm>Defines a procedural interface for developing PCP client applications. It is the Performance Metrics Application Programming Interface (PMAPI).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmclient</literal></term> +<listitem><para><indexterm id="IG3134017741"><primary>pmclient tool</primary></indexterm>Is a simple client that uses the PMAPI to report some high-level system performance metrics. The source code for <command>pmclient</command> is included in the distribution.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmda</command></term> +<listitem><para><indexterm id="IG3134017742"><primary>pmda library</primary><see>PMDA</see></indexterm>Is a library used by many shipped PMDAs to communicate with a <command>pmcd</command> process. It can expedite the development of new and custom PMDAs.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmgenmap</command></term> +<listitem><para><indexterm id="IG3134017743"><primary>pmgenmap tool</primary></indexterm>Generates C declarations and <literal>cpp</literal> macros to aid the development of customized programs that use the facilities of PCP. It is a program development tool.</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +<section id="LE16056-PARENT"> + +<title>PMDA Development</title> +<para><indexterm id="IG3134017744"><primary>PMDA</primary><secondary>development</secondary></indexterm>A collection of Performance Metrics Domain Agents (PMDAs) are provided with PCP to extract performance metrics. Each PMDA encapsulates domain-specific knowledge and methods about performance metrics that implement the uniform access protocols and functional semantics of the PCP. There is one PMDA for the operating system, another for process specific statistics, one each for common DBMS products, and so on. Thus, the range of performance metrics can be easily extended by implementing and integrating new PMDAs. <xref linkend="LE98072-PARENT"/>, is a step-by-step guide to writing your own PMDA.</para> +<section id="id5178205"> + +<title>Overview</title> +<para>Once you are familiar with the PCP and PMDA frameworks, you can quickly implement a new PMDA with only a few data structures and functions. This book contains detailed discussions of PMDA architecture and the integration of PMDAs into the PCP framework. This includes integration with PMCD. However, details of extracting performance metrics from the underlying instrumentation vary from one domain to another and are not covered in this book.</para> +<para>A PMDA is responsible for a set of performance metrics, in the sense that it must respond to requests from PMCD for information about performance metrics, instance domains, and instantiated values. The PMCD process generates requests on behalf of monitoring tools that make requests using PMAPI functions.</para> +<para>You can incorporate new performance metrics into the PCP framework by creating a PMDA, then reconfiguring PMCD to communicate with the new PMDA.</para> +</section> +<section id="id5178242"> + +<title>Building a PMDA</title> +<para>A PMDA interacts with PMCD across one of several well-defined interfaces and protocol mechanisms. These implementation options are described in the <citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle>.</para> +<note><para>It is strongly recommended that code for a new PMDA be based on the source of one of the existing PMDAs below the <filename>${PCP_PMDAS_DIR}</filename> directory.</para></note> +<section id="id5178295"> + +<title>In-Process (DSO) Method</title> +<para><indexterm id="IG3134017745"><primary>DSO</primary><secondary>PMDA building</secondary></indexterm><indexterm id="IG3134017746"><primary>dlopen man page</primary></indexterm><indexterm id="IG3134017747"><primary>dynamic shared object</primary><see>DSO</see></indexterm><indexterm id="IG3134017748"><primary>interprocess communication</primary><see>IPC</see></indexterm><indexterm id="IG3134017749"><primary>IPC</primary><secondary>DSO</secondary></indexterm>This method of building a PMDA uses a Dynamic Shared Object (DSO) that is attached by PMCD, using the platform-specific shared library manipulation interfaces such as <command>dlopen(3)</command>, at initialization time. This is the highest performance option (there is no context switching and no interprocess communication (IPC) between the PMCD and the PMDA), but is operationally intractable in some situations. For example, difficulties arise where special access permissions are required to read the instrumentation behind the performance metrics (<command>pmcd</command> does not run as root), or where the performance metrics are provided by an existing process with a different protocol interface. The DSO PMDA effectively executes as part of PMCD; so great care is required when crafting a PMDA in this manner. Calls to <command>exit(1)</command> in the PMDA, or a library it uses, would cause PMCD to exit and end monitoring of that host. Other implications are discussed in <xref linkend="id5188840"/>.</para> +</section> +<section id="id5178384"> + +<title>Daemon Process Method</title> +<para><indexterm id="IG3134017750"><primary>daemon process method</primary></indexterm>Functionally, this method may be thought of as a DSO implementation with a standard <command>main</command> routine conversion wrapper so that communication with PMCD uses message passing rather than direct procedure calls. For some very basic examples, see the <filename>${PCP_PMDAS_DIR}/trivial/trivial.c</filename> and <filename>${PCP_PMDAS_DIR}/simple/simple.c</filename> source files.</para> +<para>The daemon PMDA is actually the most common, because it allows multiple threads of control, greater (different user) privileges when executing, and provides more resilient error encapsulation than the DSO method.</para> +<note><para>Of particular interest for daemon PMDA writers, the <filename>${PCP_PMDAS_DIR}/simple</filename> PMDA has implementations in C, Perl and Python.</para></note> +</section> +</section> +</section> +<section id="id5178467"> + +<title>Client Development and PMAPI</title> +<para><indexterm id="IG3134017752"><primary>client development</primary></indexterm>Application developers are encouraged to create new PCP client applications to monitor, display, and analyze performance data in a manner suited to their particular site, application suite, or information processing environment.</para> +<para><indexterm id="IG3134017755"><primary>PMAPI</primary><secondary>client development</secondary></indexterm>PCP client applications are programmed using the Performance Metrics Application Programming Interface (PMAPI), documented in <xref linkend="LE97135-PARENT"/>. The PMAPI, which provides performance tool developers with access to all of the historical and live distributed services of PCP, is the interface used by the standard PCP utilities.</para> +</section> +<section id="id5187605"> + +<title>Library Reentrancy and Threaded Applications</title> +<para><indexterm id="IG3134017756"><primary>threaded applications</primary></indexterm><indexterm id="IG3134017757"><primary>multiple threads</primary></indexterm><indexterm id="IG3134017758"><primary>library reentrancy</primary></indexterm>While the core PCP library (<command>libpcp</command>) is thread safe, the layered PMDA library (<command>libpcp_pmda</command>) is not. This is a deliberate design decision to trade-off commonly required performance and efficiency against the less common requirement for multiple threads of control to call the PCP libraries.</para> +<para>The simplest and safest programming model is to designate at most one thread to make calls into the PCP PMDA library.</para> +</section> +</chapter> + + +<chapter id="LE98072-PARENT"> + +<title>Writing a PMDA</title> +<para><indexterm id="IG3134017759"><primary>PMDA</primary><secondary>writing</secondary></indexterm>This chapter constitutes a programmer's guide to writing a Performance Metrics Domain Agent (PMDA) for Performance Co-Pilot (PCP).</para> +<para>The presentation assumes the developer is using the standard PCP <filename>libpcp_pmda</filename> library, as documented in the <command>PMDA(3)</command> and associated man pages.</para> +<section id="id5187772"> + +<title>Implementing a PMDA</title> +<para><indexterm id="IG3134017760"><primary>implementation</primary></indexterm><indexterm id="IG3134017761"><primary>design requirements</primary></indexterm>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.</para> +<para>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.</para> +<para><indexterm id="IG3134017762"><primary>target domain</primary></indexterm><indexterm id="IG3134017763"><primary>sequential log files</primary></indexterm><indexterm id="IG3134017764"><primary>snapshot files</primary></indexterm><indexterm id="IG3134017765"><primary>IPC</primary><secondary> PMDA</secondary></indexterm>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 <command>mmap</command> 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).</para> +<note><para>The choice of export methodology is typically determined by the source of the instrumentation (the target domain) rather than by the PMDA.</para></note> +<para><indexterm id="IG3134017766"><primary>PMDA</primary><secondary> checklist</secondary></indexterm><xref linkend="id5187871"/> describes the suggested steps for designing and implementing a PMDA:</para> +<procedure id="id5187871"> +<title>Creating a PMDA</title> +<step><para>Determine how to extract the metrics from the target domain.</para></step> +<step><para>Select an appropriate architecture for the PMDA (daemon or DSO, IPC, <command>pthreads</command> or single threaded).</para></step> +<step><para>Define the metrics and instances that the PMDA will support.</para></step> +<step><para>Implement the functionality to extract the metric values.</para></step> +<step><para>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 <xref linkend="LE97285-PARENT"/></para></step> +<step><para><indexterm id="IG3134017767"><primary>help text</primary><secondary>structure specification</secondary></indexterm>Specify the help file and control data structures for metrics and instances that are required by the standard PMDA implementation library functions.</para></step> +<step><para>Write code to supply the metrics and associated information to PMCD.</para></step> +<step><para>Implement any PMDA-specific callbacks, and PMDA initialization functions.</para></step> +<step><para><indexterm id="IG3134017768"><primary>dbpmda man page</primary></indexterm>Exercise and test the PMDA with the purpose-built PMDA debugger; see the <command>dbpmda(1)</command> man page.</para></step> +<step><para>Install and connect the PMDA to a running PMCD process; see the <command>pmcd(1)</command> man page.</para></step> +<step><para><indexterm id="IG3134017769"><primary>pmchart command</primary></indexterm><indexterm id="IG3134017770"><primary>pmgadgets command</primary></indexterm><indexterm id="IG3134017774"><primary>examples</primary><secondary>visualization tools</secondary></indexterm>Configure or develop tools to use the new metrics. For examples of visualization tools, see the <command>pmchart(1)</command> and <command>pmgadgets(1)</command> man pages. For examples of text-based tools, see the <command>pminfo(1)</command> and <command>pmval(1)</command> man pages.</para></step> +<step><para><indexterm id="IG3134017772"><primary>pmie command</primary></indexterm><indexterm id="IG3134017773"><primary>pmieconf command</primary></indexterm><indexterm id="IG3134017775"><primary>examples</primary><secondary>alarm tools</secondary></indexterm>Where appropriate, define <command>pmie</command> rule templates suitable for alerting or notification systems. For more information, see the <command>pmie(1)</command> and <command>pmieconf(1)</command> man pages.</para></step> +<step><para><indexterm id="IG3134017776"><primary>pmlogger command</primary></indexterm>Where appropriate, define <command>pmlogger</command> configuration templates suitable for creating PCP archives containing the new metrics. For more information, see the <command>pmlogconf(1)</command> and <command>pmlogger(1)</command> man pages.</para></step> +</procedure> +</section> +<section id="id5188149"> + +<title>PMDA Architecture</title> +<para><indexterm id="IG3134017777"><primary>architecture</primary></indexterm><indexterm id="IG3134017778"><primary>PMDA</primary><secondary>architecture</secondary></indexterm> <indexterm id="IG3134017779"><primary>DSO</primary><secondary>architecture</secondary></indexterm>This section discusses the two methods of connecting a PMDA to a PMCD process:<itemizedlist> +<listitem><para>As a separate process using some interprocess communication (IPC) protocol.</para> +</listitem> +<listitem><para>As a dynamically attached library (that is, a dynamic shared object or DSO).</para> +</listitem></itemizedlist></para> +<section id="id5188221"> + +<title>Overview</title> +<para><indexterm id="IG3134017780"><primary>PDU</primary></indexterm><indexterm id="IG3134017781"><primary>protocol data units</primary><see>PDU</see></indexterm>All PMDAs are launched and controlled by the PMCD process on the local host. PMCD receives requests from the monitoring tools and forwards them to the PMDAs. Responses, when required, are returned through PMCD to the clients. The requests fall into a small number of categories, and the PMDA must handle each request type. For a DSO PMDA, each request type corresponds to a method in the agent. For a daemon PMDA, each request translates to a message or protocol data unit (PDU) that may be sent to a PMDA from PMCD.</para> +<para>For a daemon PMDA, the following request PDUs must be supported:<variablelist> +<varlistentry> +<term><literal>PDU_FETCH</literal></term> +<listitem><para><indexterm id="IG3134017782"><primary>pmFetch man page</primary></indexterm><indexterm id="IG3134017783"><primary>PDU_FETCH</primary></indexterm>Request for metric values (see the <command>pmFetch(3)</command> man page.)</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_PROFILE</literal></term> +<listitem><para><indexterm id="IG3134017784"><primary>pmAddProfile function</primary></indexterm><indexterm id="IG3134017785"><primary>PDU_PROFILE</primary></indexterm>A list of instances required for the corresponding metrics in subsequent fetches (see the <command>pmAddProfile(3)</command> man page).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_INSTANCE_REQ</literal></term> +<listitem><para><indexterm id="IG3134017786"><primary>pmGetInDom function</primary></indexterm><indexterm id="IG3134017787"><primary>PDU_INSTANCE_REQ</primary></indexterm> Request for a particular instance domain for instance descriptions (see the <command>pmGetInDom(3)</command> man page).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_DESC_REQ</literal></term> +<listitem><para><indexterm id="IG3134017788"><primary>pmLookupDesc function</primary></indexterm><indexterm id="IG3134017789"><primary>PDU_DESC_REQ</primary></indexterm>Request for metadata describing metrics (see the <command>pmLookupDesc(3)</command> man page).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_TEXT_REQ</literal></term> +<listitem><para><indexterm id="IG3134017790"><primary>pmLookupText function</primary></indexterm><indexterm id="IG3134017791"><primary>PDU_TEXT_REQ</primary></indexterm><indexterm id="IG3134017792"><primary>help text</primary><secondary>PDU_TEXT_REQ</secondary></indexterm>Request for metric help text (see the <command>pmLookupText(3)</command> man page).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_RESULT</literal></term> +<listitem><para><indexterm id="IG3134017793"><primary>pmstore function</primary></indexterm><indexterm id="IG3134017794"><primary>PDU_RESULT</primary></indexterm>Values to store into metrics (see the <command>pmStore(3)</command> man page).</para> +</listitem></varlistentry> +</variablelist></para> +<para>The following request PDUs may optionally be supported:<variablelist> +<varlistentry> +<term><literal>PDU_PMNS_NAMES</literal></term> +<listitem><para><indexterm id="IG3134017782nat"><primary>pmLookupName function</primary></indexterm><indexterm id="IG3134017783nat"><primary>PDU_PMNS_NAMES</primary></indexterm>Request for metric names, given one or more identifiers (see the <command>pmLookupName(3)</command> man page.)</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_PMNS_CHILD</literal></term> +<listitem><para><indexterm id="IG3134017784nat"><primary>pmGetChildren function</primary></indexterm><indexterm id="IG3134017785nat"><primary>PDU_PMNS_CHILD</primary></indexterm>A list of immediate descendent nodes of a given namespace node (see the <command>pmGetChildren(3)</command> man page).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_PMNS_TRAVERSE</literal></term> +<listitem><para><indexterm id="IG3134017786nat"><primary>pmTraversePMNS function</primary></indexterm><indexterm id="IG3134017787nat"><primary>PDU_PMNS_TRAVERSE</primary></indexterm>Request for a particular sub-tree of a given namespace node (see the <command>pmTraversePMNS(3)</command> man page).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_PMNS_IDS</literal></term> +<listitem><para><indexterm id="IG3134017788nat"><primary>pmNameID function</primary></indexterm><indexterm id="IG3134017789nat"><primary>PDU_PMNS_IDS</primary></indexterm>Perform a reverse name lookup, mapping a metric identifier to a name (see the <command>pmNameID(3)</command> man page).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PDU_AUTH</literal></term> +<listitem><para><indexterm id="IG3134017790nat"><primary>__pmParseHostAttrsSpec function</primary></indexterm><indexterm id="IG3134017791nat"><primary>PDU_AUTH</primary></indexterm>Handle connection attributes (key/value pairs), such as client credentials and other authentication information (see the <command>__pmParseHostAttrsSpec(3)</command> man page).</para> +</listitem></varlistentry> +</variablelist></para> +<para>Each PMDA is associated with a unique domain number that is encoded in the domain field of metric and instance identifiers, and PMCD uses the domain number to determine which PMDA can handle the components of any given client request.</para> +</section> +<section id="LE82676-PARENT"> + +<title>DSO PMDA</title> +<para><indexterm id="IG3134017795"><primary>DSO</primary><secondary>implementation</secondary></indexterm><indexterm id="IG3134017796"><primary>dlopen man page</primary></indexterm>Each PMDA is required to implement a function that handles each of the request types. By implementing these functions as library functions, a PMDA can be implemented as a dynamically shared object (DSO) and attached by PMCD at run time with a platform-specific call, such as <command>dlopen</command>; see the <command>dlopen(3)</command> man page. This eliminates the need for an IPC layer (typically a pipe) between each PMDA and PMCD, because each request becomes a function call rather than a message exchange. The required library functions are detailed in <xref linkend="LE21831-PARENT"/>.</para> +<para>A PMDA that interacts with PMCD in this fashion must abide by a formal initialization protocol so that PMCD can discover the location of the library functions that are subsequently called with function pointers. When a DSO PMDA is installed, the PMCD configuration file, <filename>${PCP_PMCDCONF_PATH}</filename>, is updated to reflect the domain and name of the PMDA, the location of the shared object, and the name of the initialization function. The initialization sequence is discussed in <xref linkend="LE19047-PARENT"/>.</para> +<para><indexterm id="IG3134017797"><primary>simple PMDA</primary><secondary>DSO</secondary></indexterm>As superuser, install the simple PMDA as a DSO, as shown in <xref linkend="Z1033502809tls"/>, and observe the changes in the PMCD configuration file. The output may differ slightly depending on the operating system you are using, any other PMDAs you have installed or any PMCD access controls you have in place.</para> +<para><example id="Z1033502809tls"> +<title>Simple PMDA as a DSO</title> +<programlisting><userinput>cat ${PCP_PMCDCONF_PATH}</userinput> +# Performance Metrics Domain Specifications +# +# This file is automatically generated during the build +# Name Id IPC IPC Params File/Cmd +pmcd 2 dso pmcd_init ${PCP_PMDAS_DIR}/pmcd/pmda_pmcd.so +linux 60 dso linux_init ${PCP_PMDAS_DIR}/linux/pmda_linux.so +proc 3 pipe binary ${PCP_PMDAS_DIR}/linux/pmda_proc.so -d 3 +simple 254 dso simple_init ${PCP_PMDAS_DIR}/simple/pmda_simple.so</programlisting> +</example></para> +<para>As can be seen from the contents of <filename>${PCP_PMCDCONF_PATH}</filename>, the DSO version of the simple PMDA is in a library named <filename>pmda_simple.so</filename> and has an initialization function called <indexterm id="IG3134017799"><primary>simple_init function</primary></indexterm> <command>simple_init</command>. The domain of the simple PMDA is 254, as shown in the column headed <literal>Id</literal>.</para> +<note><para>For some platforms the DSO file name will not be <filename>pmda_simple.so</filename>. On Mac OS X it is <filename>pmda_simple.dylib</filename> and on Windows it is <filename>pmda_simple.dll</filename>. +</para></note> +</section> +<section id="id5188840"> + +<title>Daemon PMDA</title> +<para><indexterm id="IG31340177100"><primary>DSO</primary><secondary>disadvantages</secondary></indexterm>A DSO PMDA provides the most efficient communication between the PMDA and PMCD. This approach has some disadvantages resulting from the DSO PMDA being the same process as PMCD:</para> +<itemizedlist> +<listitem><para>An error or bug that causes a DSO PMDA to exit also causes PMCD to exit, which affects all connected client tools.</para> +</listitem> +<listitem><para>There is only one thread of control in PMCD; as a result, a computationally expensive PMDA, or worse, a PMDA that blocks for I/O, adversely affects the performance of PMCD.</para> +</listitem> +<listitem><para>PMCD runs as the "pcp" user; so all DSO PMDAs must also run as this user.</para> +</listitem> +<listitem><para>A memory leak in a DSO PMDA also causes a memory leak for PMCD.</para> +</listitem></itemizedlist> +<para>Consequently, many PMDAs are implemented as a daemon process.</para> +<para>The <filename>libpcp_pmda</filename> library is designed to allow simple implementation of a PMDA that runs as a separate process. The library functions provide a message passing layer acting as a generic wrapper that accepts PDUs, makes library calls using the standard DSO PMDA interface, and sends PDUs. Therefore, you can implement a PMDA as a DSO and then install it as either a daemon or a DSO, depending on the presence or absence of the generic wrapper.</para> +<para><indexterm id="IG31340177101"><primary>fork system call</primary></indexterm><indexterm id="IG31340177102"><primary>execv system call</primary></indexterm><indexterm id="IG31340177103"><primary>pipe</primary></indexterm>The PMCD process launches a daemon PMDA with <command>fork</command> and <command>execv</command> (or <command>CreateProcess</command> on Windows). You can easily connect a pipe to the PMDA using standard input and output. The PMCD process may also connect to a daemon PMDA using IPv4 or IPv6 TCP/IP, or UNIX domain sockets if the platform supports that; see the <command>tcp(7)</command>, <command>ip(7)</command>, <command>ipv6(7)</command> or <command>unix(7)</command> man pages.</para> +<para><indexterm id="IG31340177104"><primary>pipe</primary></indexterm><indexterm id="IG31340177105"><primary>simple PMDA</primary><secondary> as daemon</secondary></indexterm>As superuser, install the simple PMDA as a daemon process as shown in <xref linkend="Z1033576478tls"/>. Again, the output may differ due to operating system differences, other PMDAs already installed, or access control sections in the PMCD configuration file.</para> +<para><example id="Z1033576478tls"> +<title>Simple PMDA as a Daemon</title> +<para>The specification for the simple PMDA now states the connection type of <command>pipe</command> to PMCD and the executable image for the PMDA is <filename>${PCP_PMDAS_DIR}/simple/pmdasimple</filename>, using domain number 253.<programlisting># <userinput>cd ${PCP_PMDAS_DIR}/simple</userinput> +# <userinput>./Install</userinput> +... +Install simple as a daemon or dso agent? [daemon] daemon +PMCD should communicate with the daemon via pipe or socket? [pipe] pipe +... +# <userinput>cat ${PCP_PMCDCONF_PATH}</userinput> +# Performance Metrics Domain Specifications +# +# This file is automatically generated during the build +# Name Id IPC IPC Params File/Cmd +pmcd 2 dso pmcd_init ${PCP_PMDAS_DIR}/pmcd/pmda_pmcd.so +linux 60 dso linux_init ${PCP_PMDAS_DIR}/linux/pmda_linux.so +proc 3 pipe binary ${PCP_PMDAS_DIR}/linux/pmda_proc.so -d 3 +simple 253 pipe binary ${PCP_PMDAS_DIR}/simple/pmdasimple -d 253</programlisting></para> +</example></para> +</section> +<section id="id5189181"> + +<title>Caching PMDA</title> +<para><indexterm id="IG31340177106"><primary>caching PMDA</primary></indexterm>When either the cost or latency associated with collecting performance metrics is high, the PMDA implementer may choose to trade off the currency of the performance data to reduce the PMDA resource demands or the fetch latency time.</para> +<para>One scheme for doing this is called a caching PMDA, which periodically instantiates values for the performance metrics and responds to each request from PMCD with the most recently instantiated (or cached) values, as opposed to instantiating current values on demand when the PMCD asks for them.</para> +<para><indexterm id="IG31340177107"><primary>Cisco PMDA</primary></indexterm><indexterm id="IG31340177108"><primary>pmdacisco man page</primary></indexterm>The Cisco PMDA is an example of a caching PMDA. For additional information, see the contents of the <filename>${PCP_PMDAS_DIR}/cisco</filename> directory and the <command>pmdacisco(1)</command> man page.</para> +</section> +</section> +<section id="LE97285-PARENT"> + +<title>Domains, Metrics, and Instances</title> +<para>This section defines metrics and instances, discusses how they should be designed for a particular target domain, and shows how to implement support for them.</para> +<para><indexterm id="IG31340177109"><primary>examples</primary><secondary>simple and trivial PMDAs</secondary></indexterm>The examples in this section are drawn from the trivial and simple PMDAs. Refer to the <filename>${PCP_PMDAS_DIR}/trivial</filename> and <filename>${PCP_PMDAS_DIR}/simple</filename> directories, respectively, where both binaries and source code are available.</para> +<section id="id5189300"> + +<title>Overview</title> +<para><indexterm id="IG31340177110"><primary>domains</primary><secondary>definition</secondary></indexterm><indexterm id="IG31340177111"><primary>metrics</primary><secondary>definition</secondary></indexterm><firstterm>Domains</firstterm> are autonomous performance areas, such as the operating system or a layered service or a particular application. <firstterm>Metrics</firstterm> are raw performance data for a domain, and typically quantify activity levels, resource utilization or quality of service. <firstterm>Instances</firstterm> are sets of related metrics, as for multiple processors, or multiple service classes, or multiple transaction types.</para> +<para> PCP employs the following simple and uniform data model to accommodate the demands of performance metrics drawn from multiple domains:</para> +<itemizedlist> +<listitem><para>Each metric has an identifier that is unique across all metrics for all PMDAs on a particular host.</para> +</listitem> +<listitem><para>Externally, metrics are assigned names for user convenience--typically there is a 1:1 relationship between a metric name and a metric identifier.</para> +</listitem> +<listitem><para>The PMDA implementation determines if a particular metric has a singular value or a set of (zero or more) values. For instance, the metric <literal>hinv.ndisk</literal> counts the number of disks and has only one value on a host, whereas the metric <literal>disk.dev.total</literal> counts disk I/O operations and has one value for each disk on the host.</para> +</listitem> +<listitem><para>If a metric has a set of values, then members of the set are differentiated by instances. The set of instances associated with a metric is an <firstterm>instance domain</firstterm>. For example, the set of metrics <literal>disk.dev.total</literal> is defined over an instance domain that has one member per disk spindle.</para> +</listitem></itemizedlist> +<para><indexterm id="IG31340177112"><primary>metrics and instances</primary></indexterm>The selection of metrics and instances is an important design decision for a PMDA implementer. The metrics and instances for a target domain should have the following qualities:</para> +<itemizedlist> +<listitem><para>Obvious to a user</para> +</listitem> +<listitem><para>Consistent across the domain</para> +</listitem> +<listitem><para>Accurately representative of the operational and functional aspects of the domain</para> +</listitem></itemizedlist> +<para>For each metric, you should also consider these questions:</para> +<itemizedlist> +<listitem><para>How useful is this value?</para> +</listitem> +<listitem><para>What units give a good sense of scale?</para> +</listitem> +<listitem><para>What name gives a good description of the metric's meaning?</para> +</listitem> +<listitem><para>Can this metric be combined with another to convey the same useful information?</para> +</listitem></itemizedlist> +<para>As with all programming tasks, expect to refine the choice of metrics and instances several times during the development of the PMDA.</para> +</section> +<section id="id5189538"> + +<title>Domains</title> +<para>Each PMDA must be uniquely identified by PMCD so that requests from clients can be efficiently routed to the appropriate PMDA. The unique identifier, the PMDA's domain, is encoded within the metrics and instance domain identifiers so that they are associated with the correct PMDA, and so that they are unique, regardless of the number of PMDAs that are connected to the PMCD process.</para> +<para><indexterm id="IG31340177113"><primary>domains</primary><secondary>numbers</secondary></indexterm>The default domain number for each PMDA is defined in <filename>${PCP_VAR_DIR}/pmns/stdpmid</filename>. This file is a simple table of PMDA names and their corresponding domain number. However, a PMDA does not have to use this domain number--the file is only a guide to help avoid domain number clashes when PMDAs are installed and activated.</para> +<para>The domain number a PMDA uses is passed to the PMDA by PMCD when the PMDA is launched. Therefore, any data structures that require the PMDA's domain number must be set up when the PMDA is initialized, rather than declared statically. The protocol for PMDA initialization provides a standard way for a PMDA to implement this run-time initialization.</para> +<tip><para>Although uniqueness of the domain number in the <filename>${PCP_PMCDCONF_PATH}</filename> control file used by PMCD is all that is required for successful starting of PMCD and the associated PMDAs, the developer of a new PMDA is encouraged to add the default domain number for each new PMDA to the <filename>${PCP_VAR_DIR}/pmns/stdpmid.local</filename> file and then to run the <filename>Make.stdpmid</filename> script in <filename>${PCP_VAR_DIR}/pmns</filename> to recreate <filename>${PCP_VAR_DIR}/pmns/stdpmid</filename>; this file acts as a repository for documenting the known default domain numbers.</para> +</tip> +</section> +<section id="LE98565-PARENT"> + +<title>Metrics</title> +<para><indexterm id="IG31340177114"><primary>metrics</primary><secondary>definition</secondary></indexterm><indexterm id="IG31340177115"><primary>target domain</primary></indexterm>A PMDA provides support for a collection of metrics. In addition to the obvious performance metrics, and the measures of time, activity and resource utilization, the metrics should also describe how the target domain has been configured, as this can greatly affect the correct interpretation of the observed performance. For example, metrics that describe network transfer rates should also describe the number and type of network interfaces connected to the host (<literal>hinv.ninterface</literal>, <literal>network.interface.speed</literal>, <literal>network.interface.duplex</literal>, and so on)</para> +<para><indexterm id="IG31340177116"><primary>storage of metrics</primary></indexterm><indexterm id="IG31340177117"><primary>pmstore function</primary></indexterm>In addition, the metrics should describe how the PMDA has been configured. For example, if the PMDA was periodically probing a system to measure quality of service, there should be metrics for the delay between probes, the number of probes attempted, plus probe success and failure counters. It may also be appropriate to allow values to be stored (see the <command>pmstore(1)</command> man page) into the delay metric, so that the delay used by the PMDA can be altered dynamically.</para> +<section id="id5189689"> + +<title>Data Structures</title> +<para><indexterm id="IG31340177118"><primary>data structures</primary></indexterm><indexterm id="IG31340177119"><primary>pmDesc structure</primary></indexterm><indexterm id="IG31340177120"><primary>pmLookupDesc function</primary></indexterm>Each metric must be described in a <filename>pmDesc</filename> structure; see the <command>pmLookupDesc(3)</command> man page:</para> +<programlisting>typedef struct { + pmID pmid; /* unique identifier */ + int type; /* base data type */ + pmInDom indom; /* instance domain */ + int sem; /* semantics of value */ + pmUnits units; /* dimension and units */ +} pmDesc;</programlisting> +<para>This structure contains the following fields:</para> +<variablelist condition="sgi_termlength:narrow"> +<varlistentry> +<term><literal>pmid</literal></term> +<listitem><para>A unique identifier, Performance Metric Identifier (PMID), that differentiates this metric from other metrics across the union of all PMDAs</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>type</literal></term> +<listitem><para>A data type indicator showing whether the format is an integer (32 or 64 bit, signed or unsigned); float; double; string; or arbitrary aggregate of binary data</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>indom</literal></term> +<listitem><para>An instance domain identifier that links this metric to an instance domain</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>sem</literal></term> +<listitem><para>An encoding of the value's semantics (counter, instantaneous, or discrete)</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>units</literal></term> +<listitem><para>A description of the value's units based on dimension and scale in the three orthogonal dimensions of space, time, and count (or events)</para> +</listitem></varlistentry> +</variablelist> +<note><para>This information can be observed for metrics from any active PMDA using <command>pminfo</command> command line options, for example: +<literallayout class="monospaced"> $ <userinput>pminfo -d -m network.interface.out.drops</userinput> + + network.interface.out.drops PMID: 60.3.11 + Data Type: 64-bit unsigned int InDom: 60.3 0xf000003 + Semantics: counter Units: count</literallayout> +</para></note> +<para><indexterm id="IG31340177121"><primary>__pmID_int structure</primary></indexterm>Symbolic constants of the form <literal>PM_TYPE_*</literal>, <literal>PM_SEM_*</literal>, <literal>PM_SPACE_*</literal>, <literal>PM_TIME_*</literal>, and <literal>PM_COUNT_*</literal> are defined in the <filename><pcp/pmapi.h></filename> header file. You may use them to initialize the elements of a <literal>pmDesc</literal> structure. The <literal>pmID</literal> type is an unsigned integer that can be safely cast to a <filename>__pmID_int</filename> structure, which contains fields defining the metric's (PMDA's) domain, cluster, and item number as shown in <xref linkend="Z1033577630tls"/>:</para> +<para><example id="Z1033577630tls"> +<title><filename>__pmID_int</filename> Structure</title> +<programlisting>typedef struct { + int flag:1; + unsigned int domain:9; + unsigned int cluster:12; + unsigned int item:10; +} __pmID_int;</programlisting> +</example></para> +<para>For additional information, see the <filename><pcp/impl.h></filename> file.</para> +<para><indexterm id="IG31340177122"><primary>PMDA_PMID macro</primary></indexterm>The <literal>flag</literal> field should be ignored. The <literal>domain</literal> number should be set at run time when the PMDA is initialized. The <literal>PMDA_PMID</literal> macro defined in <filename><pcp/pmapi.h></filename> can be used to set the <literal>cluster</literal> and <literal>item</literal> fields at compile time, as these should always be known and fixed for a particular metric.</para> +<note><para>The three components of the PMID should correspond exactly to the three-part definition of the PMID for the corresponding metric in the PMNS described in <xref linkend="LE83854-PARENT"/>.</para> +</note> +<para><indexterm id="IG31340177123"><primary> pmdaMetric structure</primary></indexterm>A table of <filename>pmdaMetric</filename> structures should be defined within the PMDA, with one structure per metric as shown in <xref linkend="Z976036629sdc"/>. </para> +<example id="Z976036629sdc"> +<title><filename>pmdaMetric</filename> Structure</title> +<programlisting>typedef struct { + void *m_user; /* for users external use */ + pmDesc m_desc; /* metric description */ +} pmdaMetric;</programlisting> +</example> +<para>This structure contains a <filename>pmDesc</filename> structure and a handle that allows PMDA-specific structures to be associated with each metric. For example, <literal>m_user</literal> could be a pointer to a global variable containing the metric value, or a pointer to a function that may be called to instantiate the metric's value.</para> +<para><indexterm id="IG31340177124"><primary>trivial PMDA</primary><secondary>singular metric</secondary></indexterm>The trivial PMDA, shown in <xref linkend="Z963521873sdc"/>, has only a singular metric (that is, no instance domain):</para> +<example id="Z963521873sdc"> +<title>Trivial PMDA</title> +<programlisting>static pmdaMetric metrictab[] = { +/* time */ + { NULL, + { PMDA_PMID(0, 1), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, + PMDA_PMUNITS(0, 1, 0, 0, PM_TIME_SEC, 0) }, }, +}; </programlisting> +<para>This single metric (<literal>trivial.time</literal>) has the following:</para> +<itemizedlist> +<listitem><para>A PMID with a cluster of 0 and an item of 1. Note that this is not yet a complete PMID, the domain number which identifies the PMDA will be combined with it at runtime.</para> +</listitem> +<listitem><para>An unsigned 32-bit integer (<literal>PM_TYPE_U32</literal>)</para> +</listitem> +<listitem><para><indexterm id="IG31340177125"><primary>PM_INDOM_NULL instance domain</primary><secondary>data structures</secondary></indexterm>A singular value and hence no instance domain (<literal>PM_INDOM_NULL</literal>)</para> +</listitem> +<listitem><para><indexterm id="IG31340177126"><primary>PM_SEM_INSTANT semantic type</primary></indexterm>An instantaneous semantic value (<literal>PM_SEM_INSTANT</literal>)</para> +</listitem> +<listitem><para>Dimension “time” and the units “seconds”</para> +</listitem></itemizedlist> +</example> +</section> +<section id="id5190312"> + +<title>Semantics</title> +<para><indexterm id="IG31340177127"><primary>semantic types</primary></indexterm>The metric's semantics describe how PCP tools should interpret the metric's value. The following are the possible semantic types:</para> +<itemizedlist> +<listitem><para><indexterm id="IG31340177128"><primary>PM_SEM_COUNTER semantic type</primary></indexterm>Counter (<literal>PM_SEM_COUNTER</literal>)</para> +</listitem> +<listitem><para><indexterm id="IG31340177129"><primary>PM_SEM_INSTANT semantic type</primary></indexterm> Instantaneous value (<literal>PM_SEM_INSTANT</literal>)</para> +</listitem> +<listitem><para><indexterm id="IG31340177130"><primary>PM_SEM_DISCRETE semantic type</primary></indexterm>Discrete value (<literal>PM_SEM_DISCRETE</literal>)</para> +</listitem></itemizedlist> +<para>A counter should be a value that monotonically increases (or monotonically decreases, which is less likely) with respect to time, so that the rate of change should be used in preference to the actual value. Rate conversion is not appropriate for metrics with instantaneous values, as the value is a snapshot and there is no basis for assuming any values that might have been observed between snapshots. Discrete is similar to instantaneous; however, once observed it is presumed the value will persist for an extended period (for example, system configuration, static tuning parameters and most metrics with non-numeric values).</para> +<para><indexterm id="IG31340177131"><primary>counter semantics</primary></indexterm> <indexterm id="IG31340177132"><primary> instantaneous semantics</primary></indexterm> <indexterm id="IG31340177133"><primary>discrete semantics</primary></indexterm>For a given time interval covering six consecutive timestamps, each spanning two units of time, the metric values in <xref linkend="Z963522765sdc"/> are exported from a PMDA (“N/A” implies no value is available): </para> +<example id="Z963522765sdc"> +<title>Effect of Semantics on a Metric</title> +<programlisting>Timestamps: 1 3 5 7 9 11 +Value: 10 30 60 80 90 N/A</programlisting> +<para>The default display of the values would be as follows:</para> +<programlisting>Timestamps: 1 3 5 7 9 11 +Semantics: +Counter N/A 10 15 10 5 N/A +Instantaneous 10 30 60 80 90 N/A +Discrete 10 30 60 80 90 90</programlisting> +</example> +<para>Note that these interpretations of metric semantics are performed by +the monitor tool, automatically, before displaying a value and they are not +transformations that the PMDA performs.</para> +</section> +</section> +<section id="id5190481"> + +<title>Instances</title> +<para>Singular metrics have only one value and no associated instance domain. Some metrics contain a set of values that share a common set of semantics for a specific instance, such as one value per processor, or one value per disk spindle, and so on.</para> +<note><para>The PMDA implementation is solely responsible for choosing the instance identifiers that differentiate instances within the instance domain. The PMDA is also responsible for ensuring the uniqueness of instance identifiers in any instance domain, as described in <xref linkend="id5190505"/>.</para> +</note> +<section id="id5190505"> +<title>Instance Identification</title> +<para>Consistent interpretation of instances and instance domains require a few simple rules to be followed by PMDA authors. The PMDA library provides a series of <command>pmdaCache</command> routines to assist.</para> +<itemizedlist> +<listitem><para>Each internal instance identifier (numeric) must be a unique 31-bit number.</para> +</listitem> +<listitem><para>The external instance name (string) must be unique.</para> +</listitem> +<listitem><para>When the instance name contains a space, the name to the left of the first space (the short name) must also be unique.</para> +</listitem> +<listitem><para>Where an external instance name corresponds to some object or entity, there is an expectation that the association between the name and the object is fixed.</para> +</listitem> +<listitem><para>It is preferable, although not mandatory, for the association between and external instance name (string) and internal instance identifier (numeric) to be persistent.</para> +</listitem></itemizedlist> +</section> +<section id="id5190506"> + +<title>N Dimensional Data</title> +<para><indexterm id="IG31340177134"><primary>arrays</primary><secondary>N dimensional data</secondary></indexterm>Where the performance data can be represented as scalar values (singular metrics) or one-dimensional arrays or lists (metrics with an instance domain), the PCP framework is more than adequate. In the case of metrics with an instance domain, each array or list element is associated with an instance from the instance domain.</para> +<para><indexterm id="IG31340177135"><primary>two or three dimensional arrays</primary></indexterm><indexterm id="IG31340177136"><primary> multidimensional arrays</primary></indexterm>To represent two or more dimensional arrays, the coordinates must be one of the following: </para> +<itemizedlist> +<listitem><para>Mapped onto one dimensional coordinates.</para> +</listitem> +<listitem><para>Enumerated into the Performance Metrics Name Space (PMNS).</para> +</listitem></itemizedlist> +<para>For example, this 2 x 3 array of values called M can be represented as instances 1,..., 6 for a metric M:</para> +<programlisting> M[1] M[2] M[3] + M[4] M[5] M[6]</programlisting> +<para>Or they can be represented as instances 1, 2, 3 for metric M1 and instances 1, 2, 3 for metric M2:</para> +<programlisting> M1[1] M1[2] M1[3] + M2[1] M2[2] M2[3]</programlisting> +<para>The PMDA implementer must decide and consistently export this encoding from the N-dimensional instrumentation to the 1-dimensional data model of the PCP.</para> +<para>In certain special cases (for example, such as for a histogram), it may be appropriate to export an array of values as raw binary data (the type encoding in the descriptor is <literal>PM_TYPE_AGGREGATE</literal>). However, this requires the development of special PMAPI client tools, because the standard PCP tools have no knowledge of the structure and interpretation of the binary data. The usual issues of platform-depdendence must also be kept in mind for this case - endianness, word-size, alignment and so on - the (possibly remote) special PMAPI client tools may need this information in order to decode the data successfully.</para> +</section> +<section id="id5190626"> + +<title>Data Structures</title> +<para><indexterm id="IG31340177137"><primary>data structures</primary></indexterm><indexterm id="IG31340177138"><primary>pmdaInstid structure</primary></indexterm>If the PMDA is required to support instance domains, then for each instance domain the unique internal instance identifier and external instance identifier should be defined using a <filename>pmdaInstid</filename> structure as shown in <xref linkend="Z975964618sdc"/>:</para> +<example id="Z975964618sdc"> +<title><filename>pmdaInstid</filename> Structure</title> +<programlisting>typedef struct { + int i_inst; /* internal instance identifier */ + char *i_name; /* external instance identifier */ +} pmdaInstid;</programlisting> +<para>The <literal>i_inst</literal> instance identifier must be a unique integer within a particular instance domain.</para> +</example> +<para><indexterm id="IG31340177139"><primary>pmdaIndom structure</primary></indexterm>The complete instance domain description is specified in a <filename>pmdaIndom</filename> structure as shown in <xref linkend="Z975964773sdc"/>:</para> +<example id="Z975964773sdc"> +<title><filename>pmdaIndom</filename> Structure</title> +<programlisting>typedef struct { + pmInDom it_indom; /* indom, filled in */ + int it_numinst; /* number of instances */ + pmdaInstid *it_set; /* instance identifiers */ +} pmdaIndom;</programlisting> +</example> +<para><indexterm id="IG31340177140"><primary>arrays</primary><secondary>instance description</secondary></indexterm><indexterm id="IG31340177141"><primary>__pmInDom_int structure</primary></indexterm>The <literal>it_indom</literal> element contains a <literal>pmInDom</literal> that must be unique across every PMDA. The other fields of the <filename>pmdaIndom</filename> structure are the number of instances in the instance domain and a pointer to an array of instance descriptions.</para> +<para><xref linkend="Z1033578294tls"/> shows that the <literal>pmInDom</literal> can be safely cast to <literal>__pmInDom_int</literal>, which specifies the PMDA's domain and the instance number within the PMDA:</para> +<para><example id="Z1033578294tls"> +<title><literal>__pmInDom_int</literal> Structure</title> +<programlisting>typedef struct { + int flag:1; + unsigned int domain:9; /* the administrative PMD */ + unsigned int serial:22; /* unique within PMD */ +} __pmInDom_int;</programlisting> +</example></para> +<para>As with metrics, the PMDA domain number is not necessarily known until run time; so the <literal>domain</literal> field must be set up when the PMDA is initialized.</para> +<para><indexterm id="IG31340177142"><primary>pmdaInit man page</primary></indexterm>For information about how an instance domain may also be associated with more than one metric, see the <command>pmdaInit(3)</command> man page.</para> +<para>The simple PMDA, shown in <xref linkend="Z963524114sdc"/>, has five metrics and two instance domains of three instances.</para> +<example id="Z963524114sdc"> +<title>Simple PMDA</title> +<programlisting>/* + * list of instances + */ +static pmdaInstid color[] = { + { 0, “red” }, { 1, “green” }, { 2, “blue” } +}; +static pmdaInstid *timenow = NULL; +static unsigned int timesize = 0; +/* + * list of instance domains + */ +static pmdaIndom indomtab[] = { +#define COLOR_INDOM 0 + { COLOR_INDOM, 3, color }, +#define NOW_INDOM 1 + { NOW_INDOM, 0, NULL }, +}; +/* + * all metrics supported in this PMDA - one table entry for each + */ +static pmdaMetric metrictab[] = { +/* numfetch */ + { NULL, + { PMDA_PMID(0, 0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, + PMDA_PMUNITS(0, 0, 0, 0, 0, 0) }, }, +/* color */ + { NULL, + { PMDA_PMID(0, 1), PM_TYPE_32, COLOR_INDOM, PM_SEM_INSTANT, + PMDA_PMUNITS(0, 0, 0, 0, 0, 0) }, }, +/* time.user */ + { NULL, + { PMDA_PMID(1, 2), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER, + PMDA_PMUNITS(0, 1, 0, 0, PM_TIME_SEC, 0) }, }, +/* time.sys */ + { NULL, + { PMDA_PMID(1,3), PM_TYPE_DOUBLE, PM_INDOM_NULL, PM_SEM_COUNTER, + PMDA_PMUNITS(0, 1, 0, 0, PM_TIME_SEC, 0) }, }, +/* now */ + { NULL, + { PMDA_PMID(2,4), PM_TYPE_U32, NOW_INDOM, PM_SEM_INSTANT, + PMDA_PMUNITS(0, 0, 0, 0, 0, 0) }, }, +};</programlisting> +</example> +<para><indexterm id="IG31340177143"><primary>COLOR_INDOM</primary></indexterm>The metric <literal>simple.color</literal> is associated, via <literal>COLOR_INDOM</literal>, with the first instance domain listed in <filename>indomtab</filename>. PMDA initialization assigns the correct domain portion of the instance domain identifier in <filename>indomtab[0].it_indom</filename> and <filename>metrictab[1].m_desc.indom</filename>. This instance domain has three instances: red, green, and blue.</para> +<para>The metric <literal>simple.now</literal> is associated, via <literal>NOW_INDOM</literal><indexterm id="IG31340177144"><primary>NOW_INDOM</primary></indexterm>, with the second instance domain listed in <filename>indomtab</filename>. PMDA initialization assigns the correct domain portion of the instance domain identifier in <filename>indomtab[1].it_indom</filename> and <filename>metrictab[4].m_desc.indom</filename>. This instance domain is dynamic and initially has no instances.</para> +<para><indexterm id="IG31340177145"><primary>PM_INDOM_NULL instance domain</primary><secondary>data structures</secondary></indexterm>All other metrics are singular, as specified by <literal>PM_INDOM_NULL</literal>.</para> +<para>In some cases an instance domain may vary dynamically after PMDA initialization (for example, <literal>simple.now</literal>), and this requires some refinement of the default functions and data structures of the <filename>libpcp_pmda</filename> library. Briefly, this involves providing new functions that act as wrappers for <command>pmdaInstance</command> and <command>pmdaFetch</command> while understanding the dynamics of the instance domain, and then overriding the instance and fetch methods in the <filename>pmdaInterface</filename> structure during PMDA initialization.</para> +<para>For the simple PMDA, the wrapper functions are <command>simple_fetch</command> and <command>simple_instance</command>, and defaults are over-ridden by the following assignments in the <command>simple_init</command> function:</para> +<programlisting>dp->version.any.fetch = simple_fetch; +dp->version.any.instance = simple_instance;</programlisting> +</section> +</section> +</section> +<section id="id5191164"> + +<title>Other Issues</title> +<para>Other issues include extracting the information, latency and threads of control, Name Space, PMDA help text, and management of evolution within a PMDA.</para> +<section id="id5191177"> + +<title>Extracting the Information</title> +<para><indexterm id="IG31340177146"><primary>information extraction</primary></indexterm>A suggested approach to writing a PMDA is to write a standalone program to extract the values from the target domain and then incorporate this program into the PMDA framework. This approach avoids concurrent debugging of two distinct problems: +<itemizedlist> +<listitem><para><indexterm id="IG31340177147"><primary>exporting data</primary></indexterm> Extraction of the data</para> +</listitem> +<listitem><para>Communication with PMCD</para> +</listitem></itemizedlist></para> +<para><indexterm id="IG31340177148"><primary>target domain</primary></indexterm>These are some possible ways of exporting the data from the target domain:</para> +<itemizedlist> +<listitem><para>Accumulate the performance data in a public shared memory segment.</para> +</listitem> +<listitem><para>Write the performance data to the end of a log file.</para> +</listitem> +<listitem><para>Periodically rewrite a file with the most recent values for the performance data.</para> +</listitem> +<listitem><para>Implement a protocol that allows a third party to connect to the target application, send a request, and receive new performance data.</para> +</listitem> +<listitem><para>If the data is in the operating system kernel, provide a kernel interface (preferred) to export the performance data.</para> +</listitem></itemizedlist> +<para>Most of these approaches require some further data processing by the PMDA.</para> +</section> +<section id="id5191305"> + +<title>Latency and Threads of Control</title> +<para><indexterm id="IG31340177149"><primary>latency</primary></indexterm><indexterm id="IG31340177150"><primary>control threads</primary></indexterm><indexterm id="IG31340177151"><primary>delays</primary></indexterm>The PCP protocols expect PMDAs to return the current values for performance metrics when requested, and with short delay (low latency). For some target domains, access to the underlying instrumentation may be costly or involve unpredictable delays (for example, if the real performance data is stored on some remote host or network device). In these cases, it may be necessary to separate probing for new performance data from servicing PMCD requests.</para> +<para><indexterm id="IG31340177152"><primary>pthreads man page</primary></indexterm>An architecture that has been used successfully for several PMDAs is to create one or more child processes to obtain information while the main process communicates with PMCD.</para> +<para>At the simplest deployment of this arrangement, the two processes may execute without synchronization. Threads have also been used as a more portable multithreading mechanism; see the <command>pthreads(7)</command> man page.</para> +<para>By contrast, a complex deployment would be one in which the refreshing of the metric values must be atomic, and this may require double buffering of the data structures. It also requires coordination between parent and child processes.</para> +<warning><para>Since certain data structures used by the PMDA library are not thread-aware, only one PMDA thread of control should call PMDA library functions - this would typically be the thread servicing requests from PMCD.</para> +</warning> +<para><indexterm id="IG31340177153"><primary>caching PMDA</primary></indexterm>One caveat about this style of caching PMDA--in this (special) case it is better if the PMDA converts counts to rates based upon consecutive periodic sampling from the underlying instrumentation. By exporting precomputed rate metrics with instantaneous semantics, the PMDA prevents the PCP monitor tools from computing their own rates upon consecutive PMCD fetches (which are likely to return identical values from a caching PMDA). The finer points of metric semantics are discussed in <xref linkend="id5190312"/></para> +</section> +<section id="LE83854-PARENT"> + +<title>Name Space</title> +<para><indexterm id="IG31340177154"><primary>pmns man page</primary></indexterm><indexterm id="IG31340177155"><primary>name space</primary></indexterm>The PMNS file defines the name space of the PMDA. It is a simple text file that is used during installation to expand the Name Space of the PMCD process. The format of this file is described by the <command>pmns(5)</command> man page and its hierarchical nature, syntax, and helper tools are further described in the <citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle>.</para> +<para>Client processes will not be able to access the PMDA metrics if the PMNS file is not installed as part of the PMDA installation procedure on the collector host. The installed list of metric names and their corresponding PMIDs can be found in <filename>${PCP_VAR_DIR}/pmns/root</filename>.</para> +<para><indexterm id="IG31340177156"><primary>simple PMDA</primary><secondary> 2 branches, 4 metrics</secondary></indexterm><xref linkend="Z963526380sdc"/> shows the simple PMDA, which has five metrics:<itemizedlist> +<listitem><para>Three metrics immediately under the <literal>simple</literal> node</para> +</listitem> +<listitem><para>Two metrics under another non-terminal node called <literal>simple.time</literal></para> +</listitem></itemizedlist></para> +<example id="Z963526380sdc"> +<title><filename>pmns</filename> File for the Simple PMDA</title> +<programlisting>simple { + numfetch SIMPLE:0:0 + color SIMPLE:0:1 + time + now SIMPLE:2:4 +} +simple.time { + user SIMPLE:1:2 + sys SIMPLE:1:3 +}</programlisting> +</example> +<para>Metrics that have different clusters do not have to be specified in different subtrees of the PMNS. <xref linkend="Z976046292sdc"/> shows an alternative PMNS for the simple PMDA:</para> +<example id="Z976046292sdc"> +<title>Alternate <filename>pmns</filename> File for the Simple PMDA</title> +<programlisting>simple { + numfetch SIMPLE:0:0 + color SIMPLE:0:1 + usertime SIMPLE:1:2 + systime SIMPLE:1:3 +}</programlisting> +<para>In this example, the <literal>SIMPLE</literal> macro is replaced by the domain number listed in <filename>${PCP_VAR_DIR}/pmns/stdpmid</filename> for the corresponding PMDA during installation (for the simple PMDA, this would normally be the value 253).</para> +</example> +<para>If the PMDA implementer so chooses, all or a subset of the metric names and identifiers can be specified programatically. In this situation, a special asterisk syntax is used to denote those subtrees which are to be handles this way. <xref linkend="Z976046292nat"/> shows this dynamic namespace syntax, for all metrics in the simple PMDA:</para> +<example id="Z976046292nat"> +<title>Dynamic metrics <filename>pmns</filename> File for the Simple PMDA</title> +<programlisting>simple SIMPLE:*:*</programlisting> +<para>In this example, like the one before, the <literal>SIMPLE</literal> macro is replaced by the domain number, and all (simple.*) metric namespace operations must be handled by the PMDA. This is in contrast to the static metric name model earlier, where the host-wide PMNS file is updated and used by PMCD, acting on behalf of the agent.</para> +</example> +</section> +<section id="LE72473-PARENT"> + +<title>PMDA Help Text</title> +<para><indexterm id="IG31340177157"><primary>PMDA</primary><secondary>help text</secondary></indexterm><indexterm id="IG31340177158"><primary>help text</primary><secondary>terse and extended descriptions</secondary></indexterm>For each metric defined within a PMDA, the PMDA developer is strongly encouraged to provide both terse and extended help text to describe the metric, and perhaps provide hints about the expected value ranges.</para> +<para><indexterm id="IG31340177159"><primary>newhelp man page</primary></indexterm>The help text is used to describe each metric in the visualization tools and <command>pminfo</command> with the <command>-T</command> option. The help text, such as the help text for the simple PMDA in <xref linkend="Z963526754sdc"/>, is specified in a specially formatted file, normally called <filename>help</filename>. This file is converted to the expected run-time format using the <command>newhelp</command> command; see the <command>newhelp(1)</command> man page. Converted help text files are usually placed in the PMDA's directory below <filename>${PCP_PMDAS_DIR}</filename> as part of the PMDA installation procedure.</para> +<example id="Z963526754sdc"> +<title>Help Text for the Simple PMDA</title> +<para>The two instance domains and five metrics have a short and a verbose description. Each entry begins with a line that starts with the character “@” and is followed by either the metric name (<literal>simple.numfetch</literal>) or a symbolic reference to the instance domain number (<literal>SIMPLE.1</literal>), followed by the short description. The verbose description is on the following lines, terminated by the next line starting with “@” or end of file:</para> +<programlisting>@ SIMPLE.0 Instance domain “colour” for simple PMDA +Universally 3 instances, “red” (0), “green” (1) and “blue” (3). + +@ SIMPLE.1 Dynamic instance domain “time” for simple PMDA +An instance domain is computed on-the-fly for exporting current time +information. Refer to the help text for simple.now for more details. + +@ simple.numfetch Number of pmFetch operations. +The cumulative number of pmFetch operations directed to “simple” PMDA. + +This counter may be modified with pmstore(1). + +@ simple.color Metrics which increment with each fetch +This metric has 3 instances, designated “red”, “green” and “blue”. + +The value of the metric is monotonic increasing in the range 0 to +255, then back to 0. The different instances have different starting +values, namely 0 (red), 100 (green) and 200 (blue). + +The metric values my be altered using pmstore(1). + +@ simple.time.user Time agent has spent executing user code +The time in seconds that the CPU has spent executing agent user code. + +@ simple.time.sys Time agent has spent executing system code +The time in seconds that the CPU has spent executing agent system code. + +@ simple.now Time of day with a configurable instance domain +The value reflects the current time of day through a dynamically +reconfigurable instance domain. On each metric value fetch request, +the agent checks to see whether the configuration file in +${PCP_PMDAS_DIR}/simple/simple.conf has been modified - if it has then +the file is re-parsed and the instance domain for this metric is again +constructed according to its contents. + +This configuration file contains a single line of comma-separated time +tokens from this set: + “sec” (seconds after the minute), + “min” (minutes after the hour), + “hour” (hour since midnight). + +An example configuration file could be: sec,min,hour +and in this case the simple.now metric would export values for the +three instances “sec”, “min” and “hour” corresponding respectively to +the components seconds, minutes and hours of the current time of day. + +The instance domain reflects each token present in the file, and the +values reflect the time at which the PMDA processes the fetch.</programlisting> +</example> +</section> +<section id="id5191869"> + +<title>Management of Evolution within a PMDA</title> +<para><indexterm id="IG31340177160"><primary>new metrics</primary></indexterm><indexterm id="IG31340177161"><primary>PMDA</primary><secondary>evolution</secondary></indexterm>Evolution of a PMDA, or more particularly the underlying instrumentation to which it provides access, over time naturally results in the appearance of new metrics and the disappearance of old metrics. This creates potential problems for PMAPI clients and PCP tools that may be required to interact with both new and former versions of the PMDA.</para> +<para>The following guidelines are intended to help reduce the complexity of implementing a PMDA in the face of evolutionary change, while maintaining predictability and semantic coherence for tools using the PMAPI, and for end users of those tools.</para> +<itemizedlist> +<listitem><para><indexterm id="IG31340177162"><primary>unavailable metrics support</primary></indexterm>Try to support as full a range of metrics as possible in every version of the PMDA. In this context, <firstterm>support</firstterm> means responding sensibly to requests, even if the underlying instrumentation is not available.</para> +</listitem> +<listitem><para><indexterm id="IG31340177163"><primary>pmLookupDesc function</primary></indexterm><indexterm id="IG31340177164"><primary>pmDesc structure</primary></indexterm><indexterm id="IG31340177165"><primary>PM_TYPE_NOSUPPORT value</primary></indexterm>If a metric is not supported in a given version of the underlying instrumentation, the PMDA should respond to <command>pmLookupDesc</command> requests with a <filename>pmDesc</filename> structure whose <literal>type</literal> field has the special value <literal>PM_TYPE_NOSUPPORT</literal>. Values of fields other than <literal>pmid</literal> and <literal>type</literal> are immaterial, but <xref linkend="Z976047129sdc"/> is typically benign:</para> +<example id="Z976047129sdc"> +<title> Setting Values</title> +<programlisting>pmDesc dummy = { + .pmid = PMDA_PMID(3,0), /* pmid, fill this in */ + .type = PM_TYPE_NOSUPPORT, /* this is the important part */ + .indom = PM_INDOM_NULL, /* singular,causes no problems */ + .sem = 0, /* no semantics */ + .units = PMDA_PMUNITS(0,0,0,0,0,0) /* no units */ +};</programlisting> +</example> +</listitem> +<listitem><para><indexterm id="IG31340177166"><primary>pmFetch man page</primary></indexterm><indexterm id="IG31340177167"><primary>PM_ERR_PMID error code</primary></indexterm>If a metric lacks support in a particular version of the underlying instrumentation, the PMDA should respond to <command>pmFetch</command> requests with a <command>pmResult</command> in which no values are returned for the unsupported metric. This is marginally friendlier than the other semantically acceptable option of returning an illegal PMID error or <literal>PM_ERR_PMID</literal>.</para> +</listitem> +<listitem><para><indexterm id="IG31340177168"><primary>pmLookupText function</primary></indexterm><indexterm id="IG31340177169"><primary>help text</primary><secondary>pmLookupText function</secondary></indexterm>Help text should be updated with annotations to describe different versions of the underlying product, or product configuration options, for which a specific metric is available. This is so <command>pmLookupText</command> can always respond correctly.</para> +</listitem> +<listitem><para><indexterm id="IG31340177170"><primary>type field</primary></indexterm><indexterm id="IG31340177171"><primary>pmStore function</primary></indexterm>The <command>pmStore</command> operation should fail with return status of <literal>PM_ERR_PERMISSION</literal> if a user or application tries to amend the value of an unsupported metric.</para> +</listitem> +<listitem><para><indexterm id="IG31340177172"><primary>pmExtractValue function</primary></indexterm><indexterm id="IG31340177173"><primary>pmConvScale function</primary></indexterm><indexterm id="IG31340177174"><primary>pmAtomStr function</primary></indexterm><indexterm id="IG31340177175"><primary>pmTypeStr function</primary></indexterm><indexterm id="IG31340177176"><primary>pmPrintValue function</primary></indexterm><indexterm id="IG31340177177"><primary>PM_ERR_CONV error code</primary></indexterm> The value extraction, conversion, and printing functions (<command>pmExtractValue</command>, <command>pmConvScale</command>, <command>pmAtomStr</command>, <command>pmTypeStr</command>, and <command>pmPrintValue</command>) return the <literal>PM_ERR_CONV</literal> error or an appropriate diagnostic string, if an attempt is made to operate on a value for which <literal>type</literal> is <literal>PM_TYPE_NOSUPPORT</literal>.</para> +<para>If performance tools take note of the <literal>type</literal> field in the <filename>pmDesc</filename> structure, they should not manipulate values for unsupported metrics. Even if tools ignore <literal>type</literal> in the metric's description, following these development guidelines ensures that no misleading value is ever returned; so there is no reason to call the extraction, conversion, and printing functions.</para> +</listitem></itemizedlist> +</section> +</section> +<section id="LE21831-PARENT"> + +<title>PMDA Interface</title> +<para><indexterm id="IG31340177178"><primary>PMDA</primary><secondary>interface</secondary></indexterm>This section describes an interface for the request handling callbacks in a PMDA. This interface is used by PMCD for communicating with DSO PMDAs and is also used by daemon PMDAs with <command>pmdaMain</command>.</para> +<section id="id5192358"> + +<title>Overview</title> +<para>Both daemon and DSO PMDAs must handle multiple request types from PMCD. A daemon PMDA communicates with PMCD using the PDU protocol, while a DSO PMDA defines callbacks for each request type. To avoid duplicating this PDU processing (in the case of a PMDA that can be installed either as a daemon or as a DSO), and to allow a consistent framework, <command>pmdaMain</command> can be used by a daemon PMDA as a wrapper to handle the communication protocol using the same callbacks as a DSO PMDA. This allows a PMDA to be built as both a daemon and a DSO, and then to be installed as either.</para> +<para>To further simplify matters, default callbacks are declared in <filename><pcp/pmda.h></filename>:</para> +<itemizedlist> +<listitem><para><indexterm id="IG31340177179"><primary>pmdaFetch callback</primary></indexterm><command>pmdaFetch</command></para> +</listitem> +<listitem><para><indexterm id="IG31340177180"><primary>pmdaProfile callback</primary></indexterm><command>pmdaProfile</command></para> +</listitem> +<listitem><para><indexterm id="IG31340177181"><primary>pmdaInstance callback</primary></indexterm> <command>pmdaInstance</command></para> +</listitem> +<listitem><para><indexterm id="IG31340177182"><primary>pmdaDesc callback</primary></indexterm><command>pmdaDesc</command></para> +</listitem> +<listitem><para><indexterm id="IG31340177183"><primary>pmdaText callback</primary></indexterm> <command>pmdaText</command></para> +</listitem> +<listitem><para><indexterm id="IG31340177184"><primary>pmdaStore callback</primary></indexterm> <command>pmdaStore</command></para> +</listitem> +<listitem><para><indexterm id="IG31340177nat"><primary>pmdaPMID callback</primary></indexterm> <command>pmdaPMID</command></para> +</listitem> +<listitem><para><indexterm id="IG31340178nat"><primary>pmdaName callback</primary></indexterm> <command>pmdaName</command></para> +</listitem> +<listitem><para><indexterm id="IG31340179nat"><primary>pmdaChildren callback</primary></indexterm> <command>pmdaChildren</command></para> +</listitem> +<listitem><para><indexterm id="IG31340180nat"><primary>pmdaAttribute callback</primary></indexterm> <command>pmdaAttribute</command></para> +</listitem></itemizedlist> +<para><indexterm id="IG31340177185"><primary>pmdaExt structure</primary></indexterm>Each callback takes a <filename>pmdaExt</filename> structure as its last argument. This structure contains all the information that is required by the default callbacks in most cases. The one exception is <command>pmdaFetch</command>, which needs an additional callback to instantiate the current value for each supported combination of a performance metric and an instance.</para> +<para>Therefore, for most PMDAs all the communication with PMCD is automatically handled by functions in <filename>libpcp.so</filename> and <filename>libpcp_pmda.so</filename>.</para> +<section id="id5192570"> + +<title>Trivial PMDA</title> +<para><indexterm id="IG31340177186"><primary>trivial PMDA</primary><secondary>callbacks</secondary></indexterm>The trivial PMDA uses all of the default callbacks as shown in <xref linkend="Z964109292sdc"/>. The additional callback for <command>pmdaFetch</command> is defined as <command>trivial_fetchCallBack</command>:</para> +<example id="Z964109292sdc"> +<title>Request Handling Callbacks in the Trivial PMDA</title> +<programlisting>static int +trivial_fetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *atom) +{ + __pmID_int *idp = (__pmID_int *)&(mdesc->m_desc.pmid); + + if (idp->cluster != 0 || idp->item != 0) + return PM_ERR_PMID; + if (inst != PM_IN_NULL) + return PM_ERR_INST; + atom->l = time(NULL); + return 0; +}</programlisting> +<para><indexterm id="IG31340177187"><primary>trivial_init function</primary></indexterm>This function checks that the PMID and instance are valid, and then places the metric value for the current time into the <filename>pmAtomValue</filename> structure.</para> +</example> +<para>The callback is set up by a call to <command>pmdaSetFetchCallBack</command> in <command>trivial_init</command>. As a rule of thumb, the API routines with named ending with <command>CallBack</command> are helpers for the higher PDU handling routines like <command>pmdaFetch</command>. The latter are set directly using the PMDA Interface Structures, as described in <xref linkend="id5193658"/>.</para> +</section> +<section id="id5192681"> + +<title>Simple PMDA</title> +<para><indexterm id="IG31340177188"><primary>simple PMDA</primary><secondary>pmdaFetch callback</secondary></indexterm><indexterm id="IG31340177189"><primary>simple_init function</primary></indexterm>The simple PMDA callback for <command>pmdaFetch</command> is more complicated because it supports more metrics, some metrics are instantiated with each fetch, and one instance domain is dynamic. The default <command>pmdaFetch</command> callback, shown in <xref linkend="Z964110950sdc"/>, is replaced by <command>simple_fetch</command> in <command>simple_init</command>, which increments the number of fetches and updates the instance domain for <literal>INDOM_NOW</literal> before calling <command>pmdaFetch</command>:</para> +<example id="Z964110950sdc"> +<title>Request Handling Callbacks in the Simple PMDA</title> +<programlisting>static int +simple_fetch(int numpmid, pmID pmidlist[], pmResult **resp, pmdaExt *pmda) +{ + numfetch++; + simple_timenow_check(); + simple_timenow_refresh(); + return pmdaFetch(numpmid, pmidlist, resp, pmda); +}</programlisting> +</example> +<para><indexterm id="IG31340177190"><primary>pmAtomValue structure</primary></indexterm>The callback for <command>pmdaFetch</command> is defined as <command>simple_fetchCallBack</command>. The PMID is extracted from the <filename>pmdaMetric</filename> structure, and if valid, the appropriate field in the <filename>pmAtomValue</filename> structure is set. The available types and associated fields are described further in <xref linkend="LE11914-PARENT"/> and <xref linkend="Z976562908sdc"/>.</para> +<note><para>Note that PMID validity checking need only check the cluster and item numbers, the domain number is guaranteed to be valid and the PMDA should make no assumptions about the actual domain number being used at this point.</para></note> +<para>The <literal>simple.numfetch</literal> metric has no instance domain and is easily handled first as shown in <xref linkend="Z976306482sdc"/>:</para> +<example id="Z976306482sdc"> +<title><literal>simple.numfetch</literal> Metric</title> +<programlisting>static int +simple_fetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmAtomValue *atom) +{ + int i; + static int oldfetch; + static double usr, sys; + __pmID_int *idp = (__pmID_int *)&(mdesc->m_desc.pmid); + + if (inst != PM_IN_NULL && + !(idp->cluster == 0 && idp->item == 1) && + !(idp->cluster == 2 && idp->item == 4)) + return PM_ERR_INST; + if (idp->cluster == 0) { + if (idp->item == 0) { /* simple.numfetch */ + atom->l = numfetch; + }</programlisting> +</example> +<para><indexterm id="IG31340177191"><primary>simple.color metric</primary></indexterm>In <xref linkend="Z976049747sdc"/>, the <literal>inst</literal> parameter is used to specify which instance is required for the <literal>simple.color</literal> metric:</para> +<example id="Z976049747sdc"> +<title><literal>simple.color</literal> Metric</title> +<programlisting> else if (idp->item == 1) { /* simple.color */ + switch (inst) { + case 0: /* red */ + red = (red + 1) % 256; + atom->l = red; + break; + case 1: /* green */ + green = (green + 1) % 256; + atom->l = green; + break; + case 2: /* blue */ + blue = (blue + 1) % 256; + atom->l = blue; + break; + default: + return PM_ERR_INST; + } + } + else + return PM_ERR_PMID;</programlisting> +</example> +<para><indexterm id="IG31340177192"><primary>simple.time metric</primary></indexterm>In <xref linkend="Z976049353sdc"/>, the <literal>simple.time</literal> metric is in a second cluster and has a simple optimization to reduce the overhead of calling <command>times</command> twice on the same fetch and return consistent values from a single call to <command>times</command> when both metrics <literal>simple.time.user</literal> and <literal>simple.time.sys</literal> are requested in a single <command>pmFetch</command>. The previous fetch count is used to determine if the <filename>usr</filename> and <filename>sys</filename> values should be updated:</para> +<example id="Z976049353sdc"> +<title><literal>simple.time</literal> Metric</title> +<programlisting> else if (idp->cluster == 1) { /* simple.time */ + if (oldfetch < numfetch) { + __pmProcessRunTimes(&usr, &sys); + oldfetch = numfetch; + } + if (idp->item == 2) /* simple.time.user */ + atom->d = usr; + else if (idp->item == 3) /* simple.time.sys */ + atom->d = sys; + else + return PM_ERR_PMID; + }</programlisting> +</example> +<para><indexterm id="IG31340177193"><primary>simple.now metric</primary></indexterm>In <xref linkend="Z976049020sdc"/>, the <literal>simple.now</literal> metric is in a third cluster and uses <literal>inst</literal> again to select a specific instance from the <literal>INDOM_NOW</literal> instance domain. The values associated with instances in this instance domain are managed using the <command>pmdaCache(3)</command> helper routines, which provide efficient interfaces for managing more complex instance domains:</para> +<example id="Z976049020sdc"> +<title><literal>simple.now</literal> Metric</title> +<programlisting> else if (idp->cluster == 2) { + if (idp->item == 4) { /* simple.now */ + struct timeslice *tsp; + sts = pmdaCacheLookup(*now_indom, inst, NULL, (void *)&tsp); + if (sts != PMDA_CACHE_ACTIVE) { + if (sts < 0) + __pmNotifyErr(LOG_ERR, "pmdaCacheLookup failed: inst=%d: %s", + inst, pmErrStr(sts)); + return PM_ERR_INST; + } + atom->l = tsp->tm_field; + } + else + return PM_ERR_PMID; + }</programlisting> +</example> +</section> +<section id="id5193108"> +<title><literal>simple_store</literal> in the Simple PMDA</title> +<para><indexterm id="IG31340177194"><primary>simple.store metric</primary></indexterm><indexterm id="IG31340177195"><primary id="Z980104423sdc">pmstore function</primary></indexterm>The simple PMDA permits some of the metrics it supports to be modified by <command>pmStore</command> as shown in <xref linkend="Z964111850sdc"/>. For additional information, see the <command>pmstore(1)</command> and <command>pmStore(3)</command> man pages.</para> +<example id="Z964111850sdc"> +<title><literal>simple_store</literal> in the Simple PMDA</title> +<para><indexterm id="IG31340177196"><primary>pmdaStore callback</primary></indexterm>The <command>pmdaStore</command> callback (which returns <literal>PM_ERR_PERMISSION</literal> to indicate no metrics can be altered) is replaced by <command>simple_store</command> in <command>simple_init</command>. This replacement function must take the same arguments so that it can be assigned to the function pointer in the <filename>pmdaInterface</filename> structure.</para> +<para>The function traverses the <literal>pmResult</literal> and checks the cluster and unit of each PMID to ensure that it corresponds to a metric that can be changed. Checks are made on the values to ensure they are within range before being assigned to variables in the PMDA that hold the current values for exported metrics:</para> +<programlisting>static int +simple_store(pmResult *result, pmdaExt *pmda) +{ + int i, j, val, sts = 0; + pmAtomValue av; + pmValueSet *vsp = NULL; + __pmID_int *pmidp = NULL; + + /* a store request may affect multiple metrics at once */ + for (i = 0; i < result->numpmid; i++) { + vsp = result->vset[i]; + pmidp = (__pmID_int *)&vsp->pmid; + if (pmidp->cluster == 0) { /* storable metrics are cluster 0 */ + switch (pmidp->item) { + case 0: /* simple.numfetch */ + val = vsp->vlist[0].value.lval; + if (val < 0) { + sts = PM_ERR_SIGN; + val = 0; + } + numfetch = val; + break; + case 1: /* simple.color */ + /* a store request may affect multiple instances at once */ + for (j = 0; j < vsp->numval && sts == 0; j++) { + val = vsp->vlist[j].value.lval; + if (val < 0) { + sts = PM_ERR_SIGN; + val = 0; + } if (val > 255) { + sts = PM_ERR_CONV; + val = 255; + }</programlisting> +</example> +<para><indexterm id="IG31340177197"><primary>PM_ERR_INST error code</primary></indexterm>The <literal>simple.color</literal> metric has an instance domain that must be searched because any or all instances may be specified. Any instances that are not supported in this instance domain should cause an error value of <literal>PM_ERR_INST</literal> to be returned as shown in <xref linkend="Z976051081sdc"/>:</para> +<example id="Z976051081sdc"> +<title><literal>simple.color</literal> and <literal>PM_ERR_INST</literal> Errors</title> +<programlisting> switch (vsp->vlist[j].inst) { + case 0: /* red */ + red = val; + break; + case 1: /* green */ + green = val; + break; + case 2: /* blue */ + blue = val; + break; + default: + sts = PM_ERR_INST; + }</programlisting> +</example> +<para><indexterm id="IG31340177198"><primary>PM_ERR_PMID error code</primary></indexterm>Any other PMIDs in cluster 0 that are not supported by the simple PMDA should result in an error value of <literal>PM_ERR_PMID</literal> as shown in <xref linkend="Z976307148sdc"/>:</para> +<example id="Z976307148sdc"> +<title><literal>PM_ERR_PMID</literal> Errors</title> +<programlisting> default: + sts = PM_ERR_PMID; + break; + } + }</programlisting> +</example> +<para>Any metrics that cannot be altered should generate an error value of <literal>PM_ERR_PERMISSION</literal>, and metrics not supported by the PMDA should result in an error value of <literal>PM_ERR_PMID</literal> as shown in <xref linkend="Z976050822sdc"/>:</para> +<example id="Z976050822sdc"> +<title><literal>PM_ERR_PERMISSION</literal> and <literal>PM_ERR_PMID</literal> Errors</title> +<programlisting> else if ((pmidp->cluster == 1 && + (pmidp->item == 2 || pmidp->item == 3)) || + (pmidp->cluster == 2 && pmidp->item == 4)) { + sts = PM_ERR_PERMISSION; + break; + } + else { + sts = PM_ERR_PMID; + break; + } + } + return sts; +}</programlisting> +<para>The structure <literal>pmdaExt</literal> <replaceable>pmda</replaceable> argument is not used by the <command>simple_store</command> function above.</para> +</example> +<note><para>When using storable metrics, it is important to consider the implications. It is possible <command>pmlogger</command> is actively sampling the metric being modified, for example, which may cause unexpected results to be persisted in an archive. Consider also the use of client credentials, available via the <command>attribute</command> callback of the <filename>pmdaInterface</filename> structure, to appropriately limit access to any modifications that might be made via your storable metrics.</para></note> +</section> +<section id="id5193469"> + +<title>Return Codes for <command>pmdaFetch</command> Callbacks</title> +<para>In <literal>PMDA_INTERFACE_1</literal> and <literal>PMDA_INTERFACE_2</literal>, the return codes for the <command>pmdaFetch</command> callback function are defined:</para> +<variablelist> +<varlistentry> +<term>Value</term> +<listitem><para>Meaning</para> +</listitem></varlistentry> +<varlistentry> +<term>< 0</term> +<listitem><para>Error code (for example, <literal>PM_ERR_PMID</literal>, <literal>PM_ERR_INST</literal> or <literal>PM_ERR_AGAIN</literal>)</para> +</listitem></varlistentry> +<varlistentry> +<term>0</term> +<listitem><para>Success</para> +</listitem></varlistentry> +</variablelist> +<para>In <literal>PMDA_INTERFACE_3</literal> and all later versions, the return codes for the <command>pmdaFetch</command> callback function are defined:</para> +<variablelist> +<varlistentry> +<term>Value</term> +<listitem><para>Meaning</para> +</listitem></varlistentry> +<varlistentry> +<term>< 0</term> +<listitem><para>Error code (for example, <literal>PM_ERR_PMID</literal>, <literal>PM_ERR_INST</literal>)</para> +</listitem></varlistentry> +<varlistentry> +<term>0</term> +<listitem><para>Metric value not currently available</para> +</listitem></varlistentry> +<varlistentry> +<term>> 0</term> +<listitem><para>Success</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +<section id="id5193658"> + +<title>PMDA Structures</title> +<para><indexterm id="IG31340177199"><primary>PMDA</primary><secondary>structures</secondary></indexterm>PMDA structures used with the <filename>pcp_pmda</filename> library are defined in <filename><pcp/pmda.h></filename>. <xref linkend="Z964112160sdc"/> and <xref linkend="Z964117744sdc"/> describe the <literal>pmdaInterface</literal> and <literal>pmdaExt</literal> structures.</para> +<example id="Z964112160sdc"> +<title><literal>pmdaInterface</literal> Structure Header</title> +<para><indexterm id="IG31340177200"><primary>pmdaInterface structure</primary></indexterm>The callbacks must be specified in a <filename>pmdaInterface</filename> structure:</para> +<programlisting>typedef struct { + int domain; /* set/return performance metrics domain id here */ + struct { + unsigned int pmda_interface : 8; /* PMDA DSO version */ + unsigned int pmapi_version : 8; /* PMAPI version */ + unsigned int flags : 16; /* optional feature flags */ + } comm; /* set/return communication and version info */ + int status; /* return initialization status here */ + union { + ... +</programlisting> +</example> +<para>This structure is passed by PMCD to a DSO PMDA as an argument to the initialization function. This structure supports multiple (binary-compatible) versions--the second and subsequent versions have support for the <filename>pmdaExt</filename> structure. Protocol version one is for backwards compatibility only, and should not be used in any new PMDA.</para> +<para>To date there have been six revisions of the interface structure:</para> +<itemizedlist> +<listitem><para>Version two added the <literal>pmdaExt</literal> structure, as mentioned above.</para> +</listitem> +<listitem><para>Version three changed the fetch callback return code semantics, as mentioned in <xref linkend="id5193469"/>.</para> +</listitem> +<listitem><para>Version four added support for dynamic metric names, where the PMDA is able to create and remove metric names on-the-fly in response to changes in the performance domain (<command>pmdaPMID</command>, <command>pmdaName</command>, <command>pmdaChildren</command> interfaces)</para> +</listitem> +<listitem><para>Version five added support for per-client contexts, where the PMDA is able to track arrival and disconnection of PMAPI client tools via PMCD (<command>pmdaGetContext</command> helper routine). At the same time, support for <literal>PM_TYPE_EVENT</literal> metrics was implemented, which relies on the per-client context concepts (<command>pmdaEvent*</command> helper routines).</para> +</listitem> +<listitem><para>Version six added support for authenticated client contexts, where the PMDA is informed of user credentials and other PMCD attributes of the connection between individual PMAPI clients and PMCD (<command>pmdaAttribute</command> interface)</para> +</listitem> +</itemizedlist> +<example id="Z964112160nat"> +<title><literal>pmdaInterface</literal> Structure, Latest Version</title> +<programlisting> ... + union { + ... + /* + * PMDA_INTERFACE6 + */ + struct { + pmdaExt *ext; + int (*profile)(pmdaInProfile *, pmdaExt *); + int (*fetch)(int, pmID *, pmResult **, pmdaExt *); + int (*desc)(pmID, pmDesc *, pmdaExt *); + int (*instance)(pmInDom, int, char *, pmdaInResult **, pmdaExt *); + int (*text)(int, int, char **, pmdaExt *); + int (*store)(pmResult *, pmdaExt *); + int (*pmid)(const char *, pmID *, pmdaExt *); + int (*name)(pmID, char ***, pmdaExt *); + int (*children)(const char *, int, char ***, int **, pmdaExt *); + int (*attribute)(int, int, const char *, int, pmdaExt *); + } six; + } version; +} pmdaInterface;</programlisting> +</example> +<note><para>Each new interface version is always defined as a superset of those that preceded it, only adds fields at the end of the new structure in the union, and is always binary backwards-compatible. <literal>And thus it shall remain.</literal> +For brevity, we have shown only the latest interface version (six) above, but all prior versions still exist, build, and function. In other words, PMDAs built against earlier versions of this header structure (and PMDA library) function correctly with the latest version of the PMDA library. +</para></note> + +<example id="Z964117744sdc"> +<title><literal>pmdaExt</literal> Stucture</title> +<para><indexterm id="IG31340177201"><primary>pmdaExt structure</primary></indexterm>Additional PMDA information must be specified in a <filename>pmdaExt</filename> structure:</para> +<programlisting id="Z964117899sdc">typedef struct { + unsigned int e_flags; /* PMDA_EXT_FLAG_* bit field */ + void *e_ext; /* used internally within libpcp_pmda */ + char *e_sockname; /* socket name to pmcd */ + char *e_name; /* name of this pmda */ + char *e_logfile; /* path to log file */ + char *e_helptext; /* path to help text */ + int e_status; /* =0 is OK */ + int e_infd; /* input file descriptor from pmcd */ + int e_outfd; /* output file descriptor to pmcd */ + int e_port; /* port to pmcd */ + int e_singular; /* =0 for singular values */ + int e_ordinal; /* >=0 for non-singular values */ + int e_direct; /* =1 if pmid map to meta table */ + int e_domain; /* metrics domain */ + int e_nmetrics; /* number of metrics */ + int e_nindoms; /* number of instance domains */ + int e_help; /* help text comes via this handle */ + __pmProfile *e_prof; /* last received profile */ + pmdaIoType e_io; /* connection type to pmcd */ + pmdaIndom *e_indoms; /* instance domain table */ + pmdaIndom *e_idp; /* instance domain expansion */ + pmdaMetric *e_metrics; /* metric description table */ + pmdaResultCallBack e_resultCallBack; /* to clean up pmResult after fetch */ + pmdaFetchCallBack e_fetchCallBack; /* to assign metric values in fetch */ + pmdaCheckCallBack e_checkCallBack; /* callback on receipt of a PDU */ + pmdaDoneCallBack e_doneCallBack; /* callback after PDU is processed */ + /* added for PMDA_INTERFACE_5 */ + int e_context; /* client context id from pmcd */ + pmdaEndContextCallBack e_endCallBack; /* callback after client context closed */ +} pmdaExt;</programlisting> +</example> +<para><indexterm id="IG31340177202"><primary>pmdaConnect man page</primary></indexterm><indexterm id="IG31340177203"><primary>pmdaDSO man page</primary></indexterm><indexterm id="IG31340177204"><primary>pmdaDaemon man page</primary></indexterm><indexterm id="IG31340177205"><primary>pmdaGetOptions man page</primary></indexterm><indexterm id="IG31340177206"><primary>pmdaInit man page</primary></indexterm>The <filename>pmdaExt</filename> structure contains filenames, pointers to tables, and some variables shared by several functions in the <filename>pcp_pmda </filename>library. All fields of the <filename>pmdaInterface</filename> and <filename>pmdaExt</filename> structures can be correctly set by PMDA initialization functions; see the <command>pmdaDaemon(3)</command>, <command>pmdaDSO(3)</command>, <command>pmdaGetOptions(3)</command>, <command>pmdaInit(3)</command>, and <command>pmdaConnect(3)</command> man pages for a full description of how various fields in these structures may be set or used by <filename>pcp_pmda</filename> library functions.</para> +</section> +</section> +<section id="LE19047-PARENT"> + +<title>Initializing a PMDA</title> +<para> <indexterm id="IG31340177207"><primary>PMDA</primary><secondary>initialization</secondary></indexterm>Several functions are provided to simplify the initialization of a PMDA. These functions, if used, must be called in a strict order so that the PMDA can operate correctly.</para> +<section id="id5194056"> + +<title>Overview</title> +<para><indexterm id="IG31340177208"><primary>pmdaInterface structure</primary></indexterm>The initialization process for a PMDA involves opening help text files, assigning callback function pointers, adjusting the metric and instance identifiers to the correct domains, and much more. The initialization of a daemon PMDA also differs significantly from a DSO PMDA, since the <literal>pmdaInterface</literal> structure is initialized by <command>main</command> or the PMCD process, respectively.</para> +</section> +<section id="id5194087"> + +<title>Common Initialization</title> +<para><indexterm id="IG31340177209"><primary>DSO</primary><secondary>PMDA initialization</secondary></indexterm>As described in <xref linkend="LE82676-PARENT"/>, an initialization function is provided by a DSO PMDA and called by PMCD. Using the standard PMDA wrappers, the same function can also be used as part of the daemon PMDA initialization. This PMDA initialization function performs the following tasks:</para> +<itemizedlist> +<listitem><para>Assigning callback functions to the function pointer interface of <filename>pmdaInterface</filename></para> +</listitem> +<listitem><para>Assigning pointers to the metric and instance tables from <filename>pmdaExt</filename></para> +</listitem> +<listitem><para><indexterm id="IG31340177210"><primary>help text</primary><secondary>initialization</secondary></indexterm>Opening the help text files</para> +</listitem> +<listitem><para>Assigning the domain number to the instance domains</para> +</listitem> +<listitem><para>Correlating metrics with their instance domains</para> +</listitem></itemizedlist> +<para><indexterm id="IG31340177211"><primary>pmdaInit man page</primary></indexterm><indexterm id="IG31340177212"><primary>pmdaInit man page</primary></indexterm>If the PMDA uses the common data structures defined for the <filename>pcp_pmda</filename> library, most of these requirements can be handled by the default <command>pmdaInit</command> function; see the <command>pmdaInit(3)</command> man page.</para> +<para>Because the initialization function is the only initialization opportunity for a DSO PMDA, the common initialization function should also perform any DSO-specific functions that are required. A default implementation of this functionality is provided by the <command>pmdaDSO</command> function; see the <command>pmdaDSO(3)</command> man page.</para> +<section id="id5194313"> + +<title>Trivial PMDA</title> +<para><indexterm id="IG31340177213"><primary>trivial PMDA</primary><secondary>initialization</secondary></indexterm><indexterm id="IG31340177214"><primary>pmdaFetch callback</primary></indexterm><indexterm id="IG31340177215"><primary>trivial_init function</primary></indexterm><xref linkend="Z976058585sdc"/> shows the trivial PMDA, which has no instances (that is, all metrics have singular values) and a single callback. This callback is for the <command>pmdaFetch</command> function called <command>trivial_fetchCallBack</command>; see the <command>pmdaFetch(3)</command> man page:</para> +<example id="Z976058585sdc"> +<title>Initialization in the Trivial PMDA</title> +<programlisting>static char *username; +static int isDSO = 1; /* ==0 if I am a daemon */ + +void trivial_init(pmdaInterface *dp) +{ + if (isDSO) + pmdaDSO(dp, PMDA_INTERFACE_2, “trivial DSO”, + “${PCP_PMDAS_DIR}/trivial/help”); + else + __pmSetProcessIdentity(username); + + if (dp->status != 0) + return; + + pmdaSetFetchCallBack(dp, trivial_fetchCallBack); + pmdaInit(dp, NULL, 0, + metrictab, sizeof(metrictab)/sizeof(metrictab[0])); +}</programlisting> +</example> +<para>The trivial PMDA can execute as either a DSO or daemon PMDA. A default +installation installs it as a daemon, however, and the <command>main</command> +routine clears <replaceable>isDSO</replaceable> and sets <replaceable>username</replaceable> +accordingly.</para> +<para>The <command>trivial_init</command> routine provides the opportunity to do +any extra DSO or daemon setup before calling the library <command>pmdaInit</command>. +In the example, the help text is setup for DSO mode and the daemon is +switched to run as an unprivileged user (default is <literal>root</literal>, +but it is generally good form for PMDAs to run with the least privileges possible). +If <literal>dp->status</literal> is non-zero after the <command>pmdaDSO</command> +call, the PMDA will be removed by PMCD and cannot safely continue to use the +<command>pmdaInterface</command> structure.</para> +</section> +<section id="id5194416"> + +<title>Simple PMDA</title> +<para><indexterm id="IG31340177216"><primary>simple PMDA</primary><secondary>initialization</secondary></indexterm><indexterm id="IG31340177217"><primary>simple_init function</primary></indexterm><indexterm id="IG31340177218"><primary>PDU_RESULT</primary></indexterm><indexterm id="IG31340177219"><primary>PDU_FETCH</primary></indexterm>In <xref linkend="Z976058770sdc"/>, the simple PMDA uses its own callbacks to handle <literal>PDU_FETCH</literal> and <literal>PDU_RESULT</literal> request PDUs (for <command>pmFetch</command> and <command>pmStore</command> operations respectively), as well as providing <command>pmdaFetch</command> with the callback <command>simple_fetchCallBack</command>.</para> +<example id="Z976058770sdc"> +<title>Initialization in the Simple PMDA</title> +<programlisting>static int isDSO = 1; /* =0 I am a daemon */ +static char *username; + +void simple_init(pmdaInterface *dp) +{ + if (isDSO) + pmdaDSO(dp, PMDA_INTERFACE_2, “simple DSO”, + “${PCP_PMDAS_DIR}/simple/help”); + else + __pmSetProcessIdentity(username); + + if (dp->status != 0) + return; + + dp->version.any.fetch = simple_fetch; + dp->version.any.store = simple_store; + dp->version.any.instance = simple_instance; + pmdaSetFetchCallBack(dp, simple_fetchCallBack); + pmdaInit(dp, indomtab, sizeof(indomtab)/sizeof(indomtab[0]), + metrictab, sizeof(metrictab)/sizeof(metrictab[0])); +}</programlisting> +</example> +<para>Once again, the simple PMDA may be installed either as a daemon PMDA or a DSO PMDA. The static variable <replaceable>isDSO</replaceable> indicates whether the PMDA is running as a DSO or as a daemon. A daemon PMDA always changes the value of this variable to 0 in <literal>main</literal>, for PMDAs that can operate in both modes.</para> +<para>Remember also, as described earlier, <command>simple_fetch</command> is dealing with a single request for (possibly many) values for metrics from the PMDA, and <command>simple_fetchCallBack</command> is its little helper, dealing with just one metric and one instance (optionally, if the metric happens to have an instance domain) within that larger request.</para> +</section> +</section> +<section id="id5194563"> + +<title>Daemon Initialization</title> +<para>In addition to the initialization function that can be shared by a DSO and a daemon PMDA, a daemon PMDA must also meet the following requirements:</para> +<itemizedlist> +<listitem><para>Create the <filename>pmdaInterface</filename> structure that is passed to the initialization function</para> +</listitem> +<listitem><para>Parse any command-line arguments</para> +</listitem> +<listitem><para>Open a log file (a DSO PMDA uses PMCD's log file)</para> +</listitem> +<listitem><para>Set up the IPC connection between the PMDA and the PMCD process</para> +</listitem> +<listitem><para>Handle incoming PDUs</para> +</listitem></itemizedlist> +<para><indexterm id="IG31340177220"><primary>pmdaDaemon man page</primary></indexterm><indexterm id="IG31340177221"><primary>pmdaGetOptions man page</primary></indexterm><indexterm id="IG31340177222"><primary>pmdaOpenLog man page</primary></indexterm><indexterm id="IG31340177223"><primary>pmdaConnect man page</primary></indexterm><indexterm id="IG31340177224"><primary>pmdaMain man page</primary></indexterm>All these requirements can be handled by default initialization functions in the <filename>pcp_pmda</filename> library; see the <command>pmdaDaemon(3)</command>, <command>pmdaGetOptions(3)</command>, <command>pmdaOpenLog(3)</command>, <command>pmdaConnect(3)</command>, and <command>pmdaMain(3)</command> man pages.</para> +<note><para>Optionally, a daemon PMDA may wish to reduce or change its privilege level, as seen in <xref linkend="Z976058585sdc"/> and <xref linkend="Z976058770sdc"/>. Some performance domains <literal>require</literal> the extraction process to run as a specific user in order to access the instrumentation. Many domains require the default <literal>root</literal> level of access for a daemon PMDA.</para></note> +<para><indexterm id="IG31340177225"><primary>pmdaGetOptions man page</primary></indexterm>The simple PMDA specifies the command-line arguments it accepts using <command>pmdaGetOptions</command>, as shown in <xref linkend="Z964110483sdc"/>. For additional information, see the <command>pmdaGetOptions(3)</command> man page.</para> +<example id="Z964110483sdc"> +<title><literal>main</literal> in the Simple PMDA</title> +<programlisting>static pmLongOptions longopts[] = { + PMDA_OPTIONS_HEADER(“Options”), + PMOPT_DEBUG, + PMDAOPT_DOMAIN, + PMDAOPT_LOGFILE, + PMDAOPT_USERNAME, + PMOPT_HELP, + PMDA_OPTIONS_TEXT(“\nExactly one of the following options may appear:”), + PMDAOPT_INET, + PMDAOPT_PIPE, + PMDAOPT_UNIX, + PMDAOPT_IPV6, + PMDA_OPTIONS_END +}; +static pmdaOptions opts = { + .short_options = “D:d:i:l:pu:U:6:?”, + .long_options = longopts, +}; + +int +main(int argc, char **argv) +{ + pmdaInterface dispatch; + + isDSO = 0; + __pmSetProgname(argv[0]); + __pmGetUsername(&username); + pmdaDaemon(&dispatch, PMDA_INTERFACE_2, pmProgname, SIMPLE, + “simple.log”, “${PCP_PMDAS_DIR}/simple/help”); + + pmdaGetOptions(argc, argv, &opts, &dispatch); + if (opts.errors) { + pmdaUsageMessage(&opts); + exit(1); + } + if (opts.username) + username = opts.username; + + pmdaOpenLog(&dispatch); + simple_init(&dispatch); + simple_timenow_check(); + pmdaConnect(&dispatch); + pmdaMain(&dispatch); + + exit(0); +}</programlisting> +</example> +<para>The conditions under which <command>pmdaMain</command> will return are either unexpected error conditions (often from failed initialisation, which would already have been logged), or when PMCD closes the connection to the PMDA. In all cases the correct action to take is simply to exit cleanly, possibly after any final cleanup the PMDA may need to perform.</para> +</section> +</section> +<section id="id5194770"> + +<title>Testing and Debugging a PMDA</title> +<para>Ensuring the correct operation of a PMDA can be difficult, because the responsibility of providing metrics to the requesting PMCD process and simultaneously retrieving values from the target domain requires nearly real-time communication with two modules beyond the PMDA's control. Some tools are available to assist in this important task. <indexterm id="IG31340177226"><primary>testing and debugging</primary></indexterm> <indexterm id="IG31340177227"><primary> debugging and testing</primary></indexterm></para> +<section id="id5194836"> + +<title>Overview</title> +<para><indexterm id="IG31340177228"><primary>dbx man page</primary></indexterm>Thoroughly testing a PMDA with PMCD is difficult, although testing a daemon PMDA is marginally simpler than testing a DSO PMDA. If a DSO PMDA exits, PMCD also exits because they share a single address space and control thread.</para> +<para>The difficulty in using PMCD to test a daemon PMDA results from PMCD requiring timely replies from the PMDA in response to request PDUs. Although a timeout period can be set in <filename>${PCP_PMCDOPTIONS_PATH}</filename>, attaching a debugger (such as <command>gdb</command>) to the PMDA process might cause an already running PMCD to close its connection with the PMDA. If timeouts are disabled, PMCD could wait forever to connect with the PMDA.</para> +<para>If you suspect a PMDA has been terminated due to a timeout failure, check the PMCD log file, usually <filename>${PCP_LOG_DIR}/pmcd/pmcd.log</filename>.</para> +<para><indexterm id="IG31340177229"><primary>dbpmda man page</primary></indexterm>A more robust way of testing a PMDA is to use the <command>dbpmda</command> tool, which is similar to PMCD except that <command>dbpmda</command> provides complete control over the PDUs that are sent to the PMDA, and there are no time limits--it is essentially an interactive debugger for exercising a PMDA. See the <command>dbpmda(3)</command> man page for details.</para> +<para><indexterm id="IG31340177230"><primary>pmdbg man page</primary></indexterm>In addition, careful use of PCP debugging flags can produce useful information concerning a PMDA's behavior; see the <command>PMAPI(3)</command> and <command>pmdbg(1)</command> man pages for a discussion of the PCP debugging and tracing framework.</para> +</section> +<section id="id5195016"> + +<title>Debugging Information</title> +<para><indexterm id="IG31340177231"><primary>pmdbg man page</primary></indexterm><indexterm id="IG31340177232"><primary>debugging flags</primary><see>flags</see></indexterm><indexterm id="IG31340177233"><primary>flags</primary><secondary>debugging</secondary></indexterm>You can activate debugging flags in PMCD and most other PCP tools with the <literal>-D</literal> command-line option. Supported flags can be listed with the <command>pmdbg</command> command; see the <command>pmdbg(1)</command> man page. Setting the debug flag for PMCD in <filename>${PCP_PMCDOPTIONS_PATH}</filename> might generate too much information to be useful, especially if there are other clients and PMDAs connected to the PMCD process.</para> +<para>The PMCD debugging flag can also be changed dynamically by storing a new value into the metric <literal>pmcd.control.debug</literal>:</para> +<programlisting># <emphasis role="bold">pmstore pmcd.control.debug 5</emphasis></programlisting> +<para>Most of the <filename>pcp_pmda</filename> library functions log additional information if the <literal>DBG_TRACE_LIBPMDA</literal> flag is set within the PMDA; see the <command>PMDA(3)</command> man page. The command-line argument <command>-D</command> is trapped by <command>pmdaGetOptions</command> to set the global debugging control variable <literal>pmDebug</literal>. Adding tests within the PMDA for the <literal>DBG_TRACE_APPL0</literal>, <literal>DBG_TRACE_APPL1</literal>, and <literal>DBG_TRACE_APPL2</literal> trace flags permits different levels of information to be logged to the PMDA's log file.</para> +<para>All diagnostic, debugging, and tracing output from a PMDA should be written to the standard error stream. By convention, all debugging information is enclosed by preprocessor <literal>#ifdef</literal> <command>PCP_DEBUG</command> statements so that they can be compiled out of the program at a later stage, if required, although this is rarely done in practice.</para> +<para><indexterm id="IG31340177234"><primary>simple_store function</primary></indexterm>Adding this segment of code to the <command>simple_store</command> metric causes a timestamped log message to be sent to the current log file whenever <command>pmstore</command> attempts to change <literal>simple.numfetch</literal> and <command>pmDebug</command> has the <literal>DBG_TRACE_APPL0</literal> flag set as shown in <xref linkend="Z976060060sdc"/>:</para> +<example id="Z976060060sdc"> +<title><literal>simple.numfetch</literal> in the Simple PMDA</title> +<programlisting> case 0: /* simple.numfetch */ + x + val = vsp->vlist[0].value.lval; + if (val < 0) { + sts = PM_ERR_SIGN; + val = 0; + } +#ifdef PCP_DEBUG + if (pmDebug & DBG_TRACE_APPL0) { + __pmNotifyErr(LOG_DEBUG, + "simple: %d stored into numfetch", val); + } +#endif + numfetch = val; + break;</programlisting> +</example> +<para><indexterm id="IG31340177235"><primary>pmstore function</primary></indexterm>For a description of <command>pmstore</command>, see the <command>pmstore(1)</command> man page.</para> +</section> +<section id="id5195283"> + +<title><command>dbpmda</command> Debug Utility</title> +<para><indexterm id="IG31340177236"><primary>dbpmda man page</primary></indexterm>The <command>dbpmda</command> utility provides a simple interface to the PDU communication protocol. It allows daemon and DSO PMDAs to be tested with most request types, while the PMDA process may be monitored with a debugger, tracing utilities, and other diagnostic tools. The <command>dbpmda(1)</command> man page contains a sample session with the <filename>simple</filename> PMDA.</para> +</section> +</section> +<section id="id5195340"> + +<title>Integration of a PMDA</title> +<para><indexterm id="IG31340177237"><primary>PMDA</primary><secondary>integration</secondary></indexterm>Several steps are required to install (or remove) a PMDA from a production PMCD environment without affecting the operation of other PMDAs or related visualization and logging tools.<indexterm id="IG31340177238"><primary>integrating a PMDA</primary></indexterm></para> +<para>The PMDA typically would have its own directory below <filename>${PCP_PMDAS_DIR}</filename> into which several files would be installed. In the description in <xref linkend="LE55181-PARENT"/>, the PMDA of interest is assumed to be known by the name <filename>newbie</filename>, hence the PMDA directory would be <filename>${PCP_PMDAS_DIR}/newbie</filename>.</para> +<note><para>Any installation or removal of a PMDA involves updating files and directories that are typically well protected. Hence the procedures described in this section must be executed as the superuser.</para> +</note> +<section id="LE55181-PARENT"> + +<title>Installing a PMDA</title> +<para>A PMDA is fully installed when these tasks are completed:</para> +<itemizedlist> +<listitem><para><indexterm id="IG31340177239"><primary>help text</primary><secondary>location</secondary></indexterm>Help text has been installed in a place where the PMDA can find it, usually in the PMDA directory <filename>${PCP_PMDAS_DIR}/newbie</filename>.</para> +</listitem> +<listitem><para>The name space has been updated in the <filename>${PCP_VAR_DIR}/pmns</filename> directory.</para> +</listitem> +<listitem><para>The PMDA binary has been installed, usually in the directory <filename>${PCP_PMDAS_DIR}/newbie</filename>.</para> +</listitem> +<listitem><para>The <filename>${PCP_PMCDCONF_PATH}</filename> file has been updated.</para> +</listitem> +<listitem><para>The PMCD process has been restarted or notified (with a <literal>SIGHUP</literal> signal) that the new PMDA exists.</para> +</listitem></itemizedlist> +<para>The <filename>Makefile</filename> should include an <literal>install</literal> target to compile and link the PMDA (as a DSO, or a daemon or both) in the PMDA directory. The <literal>clobber</literal> target should remove any files created as a by-product of the <literal>install</literal> target.<indexterm id="IG31340177240"><primary>PMDA</primary><secondary>Install script</secondary></indexterm></para> +<para>You may wish to use <filename>${PCP_PMDAS_DIR}/simple/Makefile</filename> as a template for constructing a new PMDA <filename>Makefile</filename>; changing the assignment of <literal>IAM</literal> from <literal>simple</literal> to <literal>newbie</literal> would account for most of the required changes.</para> +<para>The <filename>Install</filename> script should make use of the generic procedures defined in the script <filename>${PCP_SHARE_DIR}/lib/pmdaproc.sh</filename>, and may be as straightforward as the one used for the trivial PMDA, shown in <xref linkend="Z976309325sdc"/>:</para> +<example id="Z976309325sdc"> +<title><filename>Install</filename> Script for the Trivial PMDA</title> +<programlisting>. ${PCP_DIR}/etc/pcp.env +. ${PCP_SHARE_DIR}/lib/pmdaproc.sh + +iam=trivial +pmda_interface=2 +forced_restart=false + +pmdaSetup +pmdainstall +exit 0</programlisting> +</example> +<para>The variables, shown in <xref linkend="id5195779"/>, may be assigned values to modify the behavior of the <literal>pmdaSetup</literal> and <literal>pmdainstall</literal> procedures from <filename>${PCP_SHARE_DIR}/lib/pmdaproc.sh</filename>.</para> +<table id="id5195779" frame="topbot" pgwide="wide"> + +<title>Variables to Control Behavior of Generic <filename>pmdaproc.sh</filename> Procedures</title> +<tgroup cols="3" colsep="0" rowsep="0"> +<colspec colwidth="113*"/> +<colspec colwidth="213*"/> +<colspec colwidth="67*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Shell Variable</para></entry><entry align="left" valign="bottom"><para>Use</para></entry><entry align="left" valign="bottom"><para>Default</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$iam</literal></para></entry> +<entry align="left" valign="top"><para>Name of the PMDA; assignment to this variable is mandatory.</para><para>Example: <literal>iam=newbie</literal></para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$dso_opt</literal></para></entry> +<entry align="left" valign="top"><para>Can this PMDA be installed as a DSO?</para></entry> +<entry align="left" valign="top"><para><literal>false</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$daemon_opt</literal></para></entry> +<entry align="left" valign="top"><para>Can this PMDA be installed as a daemon?</para></entry> +<entry align="left" valign="top"><para><literal>true</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$perl_opt</literal></para></entry> +<entry align="left" valign="top"><para>Is this PMDA a perl script?</para></entry> +<entry align="left" valign="top"><para><literal>false</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$python_opt</literal></para></entry> +<entry align="left" valign="top"><para>Is this PMDA a python script?</para></entry> +<entry align="left" valign="top"><para><literal>false</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$forced_restart</literal></para></entry> +<entry align="left" valign="top"><para>Must this PMDA run as <literal>root</literal> or some other non-default user? (requires PMCD restart)</para></entry> +<entry align="left" valign="top"><para><literal>true</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$pipe_opt</literal></para></entry> +<entry align="left" valign="top"><para>If installed as a daemon PMDA, is the default IPC via pipes?</para></entry> +<entry align="left" valign="top"><para><literal>true</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$socket_opt</literal></para></entry> +<entry align="left" valign="top"><para>If installed as a daemon PMDA, is the default IPC via an Internet socket?</para></entry> +<entry align="left" valign="top"><para><literal>false</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$socket_inet_def</literal></para></entry> +<entry align="left" valign="top"><para>If installed as a daemon PMDA, and the IPC method uses an Internet socket, the default port number.</para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$ipc_prot</literal></para></entry> +<entry align="left" valign="top"><para>IPC style for PDU exchanges involving a daemon PMDA; <literal>binary</literal> or <literal>text</literal>.</para></entry> +<entry align="left" valign="top"><para><literal>binary</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$check_delay</literal></para></entry> +<entry align="left" valign="top"><para>Delay in seconds between installing PMDA and checking if metrics are available.</para></entry> +<entry align="left" valign="top"><para><literal>3</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$args</literal></para></entry> +<entry align="left" valign="top"><para>Additional command-line arguments passed to a daemon PMDA.</para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$pmda_interface</literal></para></entry> +<entry align="left" valign="top"><para>Version of the <filename>libpcp_pmda</filename> library required, used to determine the version for generating help text files.</para></entry> +<entry align="left" valign="top"><para><literal>1</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$pmns_source</literal></para></entry> +<entry align="left" valign="top"><para>The name of the PMNS file (by default relative to the PMDA directory).</para></entry> +<entry align="left" valign="top"><para><literal>pmns</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$pmns_name</literal></para></entry> +<entry align="left" valign="top"><para>First-level name for this PMDA's metrics in the PMNS.</para></entry> +<entry align="left" valign="top"><para><literal>$iam</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$help_source</literal></para></entry> +<entry align="left" valign="top"><para>The name of the help file (by default relative to the PMDA directory).</para></entry> +<entry align="left" valign="top"><para><literal>help</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$pmda_name</literal></para></entry> +<entry align="left" valign="top"><para>The name of the executable for a daemon PMDA.</para></entry> +<entry align="left" valign="top"><para><literal>pmda$iam</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$dso_name</literal></para></entry> +<entry align="left" valign="top"><para>The name of the shared library for a DSO PMDA.</para></entry> +<entry align="left" valign="top"><para><literal>pmda$iam.$dso_suffix</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$dso_entry</literal></para></entry> +<entry align="left" valign="top"><para>The name of the initialization function for a DSO PMDA.</para></entry> +<entry align="left" valign="top"><para><literal>${iam}_init</literal></para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$domain</literal></para></entry> +<entry align="left" valign="top"><para>The numerical PMDA domain number (from <filename>domain.h</filename>).</para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>$SYMDOM</literal></para></entry> +<entry align="left" valign="top"><para>The symbolic name of the PMDA domain number (from <filename>domain.h</filename>).</para></entry> +<entry align="left" valign="top"><para> </para></entry></row></tbody></tgroup></table> +<para>In addition, the variables <literal>do_pmda</literal> and <literal>do_check</literal> will be set to reflect the intention to install the PMDA (as opposed to install just the PMNS) and to check the availability of the metrics once the PMDA is installed. By default, each variable is <literal>true</literal>; however, the command-line options <literal>-N</literal> and <literal>-Q</literal> to <filename>Install</filename> may be used to set the variables to <literal>false</literal>, as follows: <literal>do_pmda</literal> (<command>-N</command>) and <literal>do_check</literal> (<literal>-N</literal> or <literal>-Q</literal>).</para> +<para>The variables may also have their assignments changed by the user's response to the common prompt as shown in <xref linkend="Z976309844sdc"/>:</para> +<example id="Z976309844sdc"> +<title>Changing Variable Assignments</title> +<programlisting>You will need to choose an appropriate configuration for installation +of the ... Performance Metrics Domain Agent (PMDA). + collector collect performance statistics on this system + monitor allow this system to monitor local and/or remote systems + both collector and monitor configuration for this system</programlisting> +</example> +<para>Obviously, for anything but the most trivial PMDA, after calling the <filename>pmdaSetup</filename> procedure, the <filename>Install</filename> script should also prompt for any PMDA-specific parameters, which are typically accumulated in the <replaceable>args</replaceable> variable and used by the <literal>pmdainstall</literal> procedure.</para> +<para>The detailed operation of the <filename>pmdainstall</filename> procedure involves the following tasks:</para> +<itemizedlist> +<listitem><para>Using default assignments, and interaction where ambiguity exists, determine the PMDA type (DSO or daemon) and the IPC parameters, if any.</para> +</listitem> +<listitem><para>Copy the <filename>$pmns_source</filename> file, replacing symbolic references to <literal>SYMDOM</literal> by the desired numeric domain number from <literal>domain.</literal></para> +</listitem> +<listitem><para>Merge the PMDA's name space into the PCP name space at the non-leaf node identified by <filename>$pmns_name</filename>.</para> +</listitem> +<listitem><para>If any <command>pmchart</command> views can be found (files with names ending in “.pmchart”), copy these to the standard directory (<filename>${PCP_VAR_DIR}/config/pmchart</filename>) with the “.pmchart” suffix removed.</para> +</listitem> +<listitem><para><indexterm id="IG31340177241"><primary>help text</primary><secondary>creation</secondary></indexterm>Create new help files from <literal>$help_source</literal> after replacing symbolic references to <literal>SYMDOM</literal> by the desired numeric domain number from <literal>domain</literal>.</para> +</listitem> +<listitem><para>Terminate the old daemon PMDA, if any.</para> +</listitem> +<listitem><para>Use the <filename>Makefile</filename> to build the appropriate executables.</para> +</listitem> +<listitem><para>Add the PMDA specification to PMCD's configuration file (<filename>${PCP_PMCDCONF_PATH}</filename>).</para> +</listitem> +<listitem><para>Notify PMCD. To minimize the impact on the services PMCD provides, sending a <literal>SIGHUP</literal> to PMCD forces it to reread the configuration file and start, restart, or remove any PMDAs that have changed since the file was last read. However, if the newly installed PMDA must run using a different privilege level to PMCD then PMCD must be restarted. This is because PMCD runs unprivileged after initially starting the PMDAs.</para> +</listitem> +<listitem><para>Check that the metrics from the new PMDA are available.</para> +</listitem></itemizedlist> +<para>There are some PMDA changes that may trick PMCD into thinking nothing has changed, and not restarting the PMDA. Most notable are changes to the PMDA executable. In these cases, you may need to explicitly remove the PMDA as described in <xref linkend="Z976310185sdc"/>, or more drastically, restart PMCD as follows: <indexterm id="IG31340177242"><primary>restarting pmcd</primary></indexterm></para> +<literallayout class="monospaced"># <userinput>${PCP_RC_DIR}/pcp start</userinput></literallayout> +<para><indexterm id="IG31340177243"><primary>examples</primary><secondary>Install script</secondary></indexterm>The files <filename>${PCP_PMDAS_DIR}/*/Install</filename> provide a wealth of examples that may be used to construct a new PMDA <filename>Install</filename> script.</para> +</section> +<section id="id5197100"> + +<title>Upgrading a PMNS to Include Metrics from a New PMDA</title> +<para><indexterm id="IG31340177244"><primary>new PMDA</primary></indexterm><indexterm id="IG31340177245"><primary>PMNS</primary><secondary>upgrade</secondary></indexterm><indexterm id="IG31340177246"><primary>PMDA</primary><secondary> Install script</secondary></indexterm>When invoked with a <literal>-N</literal> command-line option, the PMDA <filename>Install</filename> script may be used to update the PMNS without installing the PMDA. This functionality is rarely, if ever, used in modern versions of PCP, but allows one to populate the local PMNS with the names of the performance metrics from a PMDA installed on a remote host. The <literal>-N</literal> option can also install <command>pmchart</command> views useful on a monitoring system, although this also is rarely used now with each platforms package management tools handling this task.</para> +</section> +<section id="Z976310185sdc"> + +<title>Removing a PMDA</title> +<para><indexterm id="IG31340177247"><primary>PMDA</primary><secondary>removal</secondary></indexterm>The simplest way to stop a PMDA from running, apart from killing the process, is to remove the entry from <filename>${PCP_PMCDCONF_PATH}</filename> and signal PMCD (with <literal>SIGHUP</literal>) to reread its configuration file. To completely remove a PMDA requires the reverse process of the installation, including an update of the Performance Metrics Name Space (PMNS).</para> +<para><indexterm id="IG31340177248"><primary>removal script</primary></indexterm>This typically involves a <filename>Remove</filename> script in the PMDA directory that uses the same common procedures as the <filename>Install</filename> script described <xref linkend="LE55181-PARENT"/>.</para> +<para><indexterm id="IG31340177249"><primary>examples</primary><secondary>Remove script</secondary></indexterm>The <filename>${PCP_PMDAS_DIR}/*/Remove</filename> files provide a wealth of examples that may be used to construct a new PMDA <filename>Remove</filename> script.</para> +</section> +<section id="id5197301"> + +<title>Configuring PCP Tools</title> +<para><indexterm id="IG31340177250"><primary>tool configuration</primary></indexterm><indexterm id="IG31340177251"><primary>configuration</primary></indexterm>Most PCP tools have their own configuration file format for specifying which metrics to view or to log. By using canned configuration files that monitor key metrics of the new PMDA, users can quickly see the performance of the target system, as characterized by key metrics in the new PMDA. </para> +<para>Any configuration files that are created should be kept with the PMDA and installed into the appropriate directories when the PMDA is installed.</para> +<para>As with all PCP customization, some of the most valuable tools can be created by defining views, scenes, and control-panel layouts that combine related performance metrics from multiple PMDAs or multiple hosts.</para> +<para><indexterm id="IG31340177254"><primary>pmlogger command</primary></indexterm><indexterm id="IG31340177255"><primary>pmlogconf command</primary></indexterm>Metrics suitable for on-going logging can be specified in templated <command>pmlogger</command> configuration files for <command>pmlogconf</command> to automatically add to the <command>pmlogger_daily</command> recorded set; see the <command>pmlogger(1)</command>, <command>pmlogconf(1)</command> and <command>pmlogger_daily(1)</command> man pages.</para> +<para><indexterm id="IG31340177252"><primary>pmie command</primary></indexterm><indexterm id="IG31340177253"><primary>pmieconf command</primary></indexterm>Parameterized alarm configurations can be created using the <command>pmieconf</command> facilities; see the <command>pmieconf(1)</command> and <command>pmie(1)</command> man pages.</para> +</section> +</section> +</chapter> + + +<chapter id="LE97135-PARENT"> + +<title>PMAPI--The Performance Metrics API</title> +<para><indexterm id="IG31340177256"><primary>PMAPI</primary><secondary>description</secondary></indexterm><indexterm id="IG31340177257"><primary>Application Programming Interface</primary></indexterm>This chapter describes the Performance Metrics Application Programming Interface (PMAPI) provided with Performance Co-Pilot (PCP).</para> +<para><indexterm id="IG31340177258"><primary>archive logs</primary><secondary>performance data</secondary></indexterm>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.</para> +<para>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.</para> +<para>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.</para> +<para>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.”</para> +<section id="LE87626-PARENT"> + +<title>Naming and Identifying Performance Metrics</title> +<para><indexterm id="IG31340177259"><primary>performance metrics</primary><see>metrics</see></indexterm><indexterm id="IG31340177260"><primary>metrics</primary><secondary>API</secondary></indexterm><indexterm id="IG31340177261"><primary>PMAPI</primary><secondary>identifying metrics</secondary></indexterm>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 <literal>hinv.physmem</literal> has a single 32-bit unsigned integer value, representing the number of megabytes of physical memory in the system, while the performance metric <literal>disk.dev.total</literal> 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 <xref linkend="LE97285-PARENT"/>.</para> +<para>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 <literal>pmID</literal>.</para> +<para>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 <xref linkend="LE98565-PARENT"/>.</para> +<para>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 <citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle>.</para> +<para>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</para> +</section> +<section id="id5197718"> + +<title>Performance Metric Instances</title> +<para><indexterm id="IG31340177262"><primary>PMAPI</primary><seealso>metrics</seealso></indexterm>When performance metric values are returned across the PMAPI to a requesting application, there may be more than one value for a particular metric; for example, independent counts for each CPU, or each process, or each disk, or each system call type, and so on. This multiplicity of values is not enumerated in the Name Space, but rather when performance metrics are delivered across the PMAPI.</para> +<para>The notion of <literal>metric instances</literal> is really a number of related concepts, as follows:</para> +<itemizedlist> +<listitem><para>A particular performance metric may have a set of associated values or instances.</para> +</listitem> +<listitem><para>The instances are differentiated by an instance identifier.</para> +</listitem> +<listitem><para>An instance identifier has an internal encoding (an integer value) and an external encoding (a corresponding external name or label).</para> +</listitem> +<listitem><para>The set of all possible instance identifiers associated with a performance metric on a particular host constitutes an <firstterm>instance domain</firstterm>.</para> +</listitem> +<listitem><para>Several performance metrics may share the same instance domain.</para> +</listitem></itemizedlist> +<para>Consider <xref linkend="Z976548024sdc"/>:</para> +<example id="Z976548024sdc"> +<title>Metrics Sharing the Same Instance Domain</title> +<programlisting><userinput>$ pminfo -f filesys.free</userinput> + +filesys.free + inst [1 or “/dev/disk0”] value 1803 + inst [2 or “/dev/disk1”] value 22140 + inst [3 or “/dev/disk2”] value 157938</programlisting> +</example> +<para>The metric <literal>filesys.free</literal> has three values, currently 1803, 22140, and 157938. These values are respectively associated with the instances identified by the internal identifiers 1, 2 and 3, and the external identifiers <filename>/dev/disk0</filename>, <filename>/dev/disk1</filename>, and <filename>/dev/disk2</filename>. These instances form an instance domain that is shared by the performance metrics <literal>filesys.capacity</literal>, <literal>filesys.used</literal>, <literal>filesys.free</literal>, <literal>filesys.mountdir</literal>, and so on.</para> +<para>Each performance metric is associated with an instance domain, while each instance domain may be associated with many performance metrics. Each instance domain is identified by a unique value, as defined by the following <literal>typedef</literal> declaration:</para> +<literallayout class="monospaced"><literal>typedef unsigned long pmInDom;</literal></literallayout> +<para><indexterm id="IG31340177263"><primary>PM_INDOM_NULL instance domain</primary><secondary>description</secondary></indexterm>The special instance domain <literal>PM_INDOM_NULL</literal> is reserved to indicate that the metric has a single value (a singular instance domain). For example, the performance metric <literal>mem.freemem</literal> always has exactly one value. Note that this is semantically different to a performance metric like <literal>kernel.percpu.cpu.sys</literal> that has a non-singular instance domain, but may have only one value available; for example, on a system with a single processor.</para> +<para><indexterm id="IG31340177264"><primary>PM_IN_NULL instance identifier</primary></indexterm>In the results returned above the PMAPI, each individual instance within an instance domain is identified by an internal integer instance identifier. The special instance identifier <literal>PM_IN_NULL</literal> is reserved for the single value in a singular instance domain. Performance metric values are delivered across the PMAPI as a set of instance identifier and value pairs.</para> +<para>The instance domain of a metric may change with time. For example, a machine may be shut down, have several disks added, and be rebooted. All performance metrics associated with the instance domain of disk devices would contain additional values after the reboot. The difficult issue of transient performance metrics means that repeated requests for the same PMID may return different numbers of values, or some changes in the particular instance identifiers returned. This means applications need to be aware that metric instantiation is guaranteed to be valid only at the time of collection.</para> +<note><para>Some instance domains are more dynamic than others. For example, consider the instance domains behind the performance metrics <literal>proc.memory.rss</literal> (one instance per process), <literal>swap.free</literal> (one instance per swap partition) and <literal>kernel.percpu.cpu.intr</literal> (one instance per CPU).</para> +</note> +</section> +<section id="id5198049"> + +<title>Current PMAPI Context</title> +<para><indexterm id="IG31340177265"><primary>PMAPI</primary><secondary>current context</secondary></indexterm>When performance metrics are retrieved across the PMAPI, they are delivered in the context of a particular source of metrics, a point in time, and a profile of desired instances. This means that the application making the request has already negotiated across the PMAPI to establish the context in which the request should be executed.</para> +<para><indexterm id="IG31340177266"><primary>archive logs</primary><secondary>performance data</secondary></indexterm>A metric's source may be the current performance data from a particular host (a live or real-time source), or an archive log of performance data collected by <command>pmlogger</command> at some remote host or earlier time (a retrospective or archive source). The metric's source is specified when the PMAPI context is created by calling the <command>pmNewContext</command> function. This function returns an opaque handle which can be used to identify the context.</para> +<para><indexterm id="IG31340177267"><primary>collection time</primary></indexterm>The collection time for a performance metric is always the current time of day for a real-time source, or current position for an archive source. For archives, the collection time may be set to an arbitrary time within the bounds of the archive log by calling the <command>pmSetMode</command> function.</para> +<para>The last component of a PMAPI context is an instance profile that may be used to control which particular instances from an instance domain should be retrieved. When a new PMAPI context is created, the initial state expresses an interest in all possible instances, to be collected at the current time. The instance profile can be manipulated using the <command>pmAddProfile</command> and <command>pmDelProfile</command> functions.</para> +<para>The current context can be changed by passing a context handle to <command>pmUseContext</command>. If a live context connection fails, the <command>pmReconnectContext</command> function can be used to attempt to reconnect it.</para> +</section> +<section id="LE11914-PARENT"> + +<title>Performance Metric Descriptions</title> +<para><indexterm id="IG31340177268"><primary>pmDesc structure</primary></indexterm>For each defined performance metric, there is associated metadata encoded in a performance metric description (<command>pmDesc</command> structure) that describes the format and semantics of the performance metric. The <command>pmDesc</command> structure, in <xref linkend="Z976548425sdc"/>, provides all of the information required to interpret and manipulate a performance metric through the PMAPI. It has the following declaration:</para> +<example id="Z976548425sdc"> +<title><command>pmDesc</command> Structure</title> +<programlisting>/* Performance Metric Descriptor */ +typedef struct { + pmID pmid; /* unique identifier */ + int type; /* base data type (see below) */ + pmInDom indom; /* instance domain */ + int sem; /* semantics of value (see below) */ + pmUnits units; /* dimension and units (see below) */ +} pmDesc;</programlisting> +</example> +<para>The <literal>type</literal> field in the <filename>pmDesc</filename> structure describes various encodings of a metric's value. Its value will be one of the following constants:</para> +<programlisting>/* pmDesc.type - data type of metric values */ +#define PM_TYPE_NOSUPPORT -1 /* not in this version */ +#define PM_TYPE_32 0 /* 32-bit signed integer */ +#define PM_TYPE_U32 1 /* 32-bit unsigned integer */ +#define PM_TYPE_64 2 /* 64-bit signed integer */ +#define PM_TYPE_U64 3 /* 64-bit unsigned integer */ +#define PM_TYPE_FLOAT 4 /* 32-bit floating point */ +#define PM_TYPE_DOUBLE 5 /* 64-bit floating point */ +#define PM_TYPE_STRING 6 /* array of char */ +#define PM_TYPE_AGGREGATE 7 /* arbitrary binary data */ +#define PM_TYPE_AGGREGATE_STATIC 8 /* static pointer to aggregate */ +#define PM_TYPE_EVENT 9 /* packed pmEventArray */ +#define PM_TYPE_UNKNOWN 255 /* used in pmValueBlock not pmDesc */</programlisting> +<para><indexterm id="IG31340177269"><primary>PM_TYPE_STRING type</primary></indexterm>By convention <literal>PM_TYPE_STRING</literal> is interpreted as a classic C-style null byte terminated string.</para> +<para><indexterm id="IG31340177269nat"><primary>PM_TYPE_EVENT type</primary></indexterm>Event records are encoded as a packed array of strongly-typed, well-defined records within a <literal>pmResult</literal> structure, using a container metric with a value of type <literal>PM_TYPE_EVENT</literal>.</para> +<para><indexterm id="IG31340177270"><primary>PM_TYPE_AGGREGATE type</primary></indexterm>If the value of a performance metric is of type <literal>PM_TYPE_STRING</literal>, <literal>PM_TYPE_AGGREGATE</literal>, <literal>PM_TYPE_AGGREGATE_STATIC</literal>, or <literal>PM_TYPE_EVENT</literal>, the interpretation of that value is unknown to many PCP components. In the case of the aggregate types, the application using the value and the Performance Metrics Domain Agent (PMDA) providing the value must have some common understanding about how the value is structured and interpreted. Strings can be manipulated using the standard C libraries. Event records contain timestamps, event flags and event parameters, and the PMAPI provides support for unpacking an event record - see the <command>pmUnpackEventRecords(3)</command> man page for details. Further discussion on event metrics and event records can be found in <xref linkend="id5199202"/>.</para> +<para><indexterm id="IG31340177271"><primary>PM_TYPE_NOSUPPORT value</primary></indexterm><literal>PM_TYPE_NOSUPPORT</literal> indicates that the PCP collection framework knows about the metric, but the corresponding service or application is either not configured or is at a revision level that does not provide support for this performance metric.</para> +<para>The semantics of the performance metric is described by the <literal>sem</literal> field of a <filename>pmDesc</filename> structure and uses the following constants:</para> +<programlisting>/* pmDesc.sem - semantics of metric values */ +#define PM_SEM_COUNTER 1 /* cumulative count, monotonic increasing */ +#define PM_SEM_INSTANT 3 /* instantaneous value continuous domain */ +#define PM_SEM_DISCRETE 4 /* instantaneous value discrete domain */</programlisting> +<para><indexterm id="IG31340177272"><primary>dimensionality and scale</primary></indexterm><indexterm id="IG31340177273"><primary>scale and dimensionality</primary></indexterm>Each value for a performance metric is assumed to be drawn from a set of values that can be described in terms of their dimensionality and scale by a compact encoding, as follows:</para> +<itemizedlist> +<listitem><para>The dimensionality is defined by a power, or index, in each of three orthogonal dimensions: Space, Time, and Count (dimensionless). For example, I/O throughput is Space<superscript>1</superscript>.Time<superscript>-1</superscript>, while the running total of system calls is Count<superscript>1</superscript>, memory allocation is Space<superscript>1</superscript>, and average service time per event is Time<superscript>1</superscript>.Count<superscript>-1</superscript>.</para> +</listitem> +<listitem><para>In each dimension, a number of common scale values are defined that may be used to better encode ranges that might otherwise exhaust the precision of a 32-bit value. For example, a metric with dimension Space<superscript>1</superscript>.Time<superscript>-1</superscript> may have values encoded using the scale megabytes per second.</para> +</listitem></itemizedlist> +<para><indexterm id="IG31340177274"><primary>pmDesc structure</primary></indexterm>This information is encoded in the <filename>pmUnits</filename> data structure, shown in <xref linkend="Z1034792511tls"/>. It is embedded in the <filename>pmDesc</filename> structure :</para> +<para>The structures are as follows:</para> +<example id="Z1034792511tls"> +<title><filename>pmUnits</filename> and <filename>pmDesc</filename> Structures</title> +<programlisting>/* + * Encoding for the units (dimensions and + * scale) for Performance Metric Values + * + * For example, a pmUnits struct of + * { 1, -1, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0 } + * represents Mbytes/sec, while + * { 0, 1, -1, 0, PM_TIME_HOUR, 6 } + * represents hours/million-events + */ +typedef struct { + int pad:8; + int scaleCount:4; /* one of PM_COUNT_* below */ + int scaleTime:4; /* one of PM_TIME_* below */ + int scaleSpace:4; /* one of PM_SPACE_* below */ + int dimCount:4; /* event dimension */ + int dimTime:4; /* time dimension */ + int dimSpace:4; /* space dimension +} pmUnits; /* dimensional units and scale of value */ +/* pmUnits.scaleSpace */ +#define PM_SPACE_BYTE 0 /* bytes */ +#define PM_SPACE_KBYTE 1 /* Kilobytes (1024) */ +#define PM_SPACE_MBYTE 2 /* Megabytes (1024^2) */ +#define PM_SPACE_GBYTE 3 /* Gigabytes (1024^3) */ +#define PM_SPACE_TBYTE 4 /* Terabytes (1024^4) */ +/* pmUnits.scaleTime */ +#define PM_TIME_NSEC 0 /* nanoseconds */ +#define PM_TIME_USEC 1 /* microseconds */ +#define PM_TIME_MSEC 2 /* milliseconds */ +#define PM_TIME_SEC 3 /* seconds */ +#define PM_TIME_MIN 4 /* minutes */ +#define PM_TIME_HOUR 5 /* hours */ +/* + * pmUnits.scaleCount (e.g. count events, syscalls, + * interrupts, etc.) -- these are simply powers of 10, + * and not enumerated here. + * e.g. 6 for 10^6, or -3 for 10^-3 + */ +#define PM_COUNT_ONE 0 /* 1 */</programlisting> +</example> +</section> +<section id="LE82331-PARENT"> + +<title>Performance Metrics Values</title> +<para><indexterm id="IG31340177275"><primary>pmFetch function</primary></indexterm><indexterm id="IG31340177276"><primary>pmStore function</primary></indexterm>An application may fetch (or store) values for a set of performance metrics, each with a set of associated instances, using a single <command>pmFetch</command> (or <command>pmStore</command>) function call. To accommodate this, values are delivered across the PMAPI in the form of a tree data structure, rooted at a <filename>pmResult</filename> structure. This encoding is illustrated in <xref linkend="id5198718"/>, and uses the component data structures in <xref linkend="Z976557818sdc"/>:</para> +<example id="Z976557818sdc"> +<title><command>pmValueBlock</command> and <command>pmValue</command> Structures</title> +<programlisting>typedef struct { + int inst; /* instance identifier */ + union { + pmValueBlock *pval; /* pointer to value-block */ + int lval; /* integer value insitu */ + } value; +} pmValue;</programlisting> +</example> +<para><figure id="id5198718"><title>A Structured Result for Performance Metrics from <command>pmFetch</command></title><mediaobject><imageobject><imagedata fileref="figures/pmresult.svg"/></imageobject><textobject><phrase>A Structured Result for Performance Metrics from pmFetch</phrase></textobject></mediaobject></figure></para> +<para><indexterm id="IG31340177277"><primary>internal instance identifier</primary></indexterm>The internal instance identifier is stored in the <literal>inst</literal> element. If a value for a particular metric-instance pair is a 32-bit integer (signed or unsigned), then it will be stored in the <literal>lval</literal> element. If not, the value will be in a <literal>pmValueBlock</literal> structure, as shown in <xref linkend="Z1034793414tls"/>, and will be located via <literal>pval</literal>:</para> +<para>The <literal>pmValueBlock</literal> structure is as follows:<example id="Z1034793414tls"> +<title><literal>pmValueBlock</literal> Structure</title> +<programlisting>typedef struct { + unsigned int vlen : 24; /* bytes for vtype/vlen + vbuf */ + unsigned int vtype : 8; /* value type */ + char vbuf[1]; /* the value */ +} pmValueBlock;</programlisting> +</example></para> +<para><indexterm id="IG31340177278"><primary>arrays</primary><secondary>performance metrics</secondary></indexterm>The length of the <filename>pmValueBlock</filename> (including the <literal>vtype</literal> and <literal>vlen</literal> fields) is stored in <literal>vlen</literal>. Despite the prototype declaration of <literal>vbuf</literal>, this array really accommodates <literal>vlen</literal> minus <command>sizeof</command>(<literal>vlen</literal>) bytes. The <literal>vtype</literal> field encodes the type of the value in the <literal>vbuf[]</literal> array, and is one of the <command>PM_TYPE_*</command> macros defined in <filename><pcp/pmapi.h></filename>.</para> +<para><indexterm id="IG31340177279"><primary>PM_VAL_INSITU value</primary></indexterm>A <filename>pmValueSet</filename> structure, as shown in <xref linkend="Z976549488sdc"/>, contains all of the values to be returned from <command>pmFetch</command> for a single performance metric identified by the <literal>pmid</literal> field.</para> +<example id="Z976549488sdc"> +<title><filename>pmValueSet</filename> Structure</title> +<programlisting>typedef struct { + pmID pmid; /* metric identifier */ + int numval; /* number of values */ + int valfmt; /* value style, insitu or ptr */ + pmValue vlist[1]; /* set of instances/values */ +} pmValueSet;</programlisting> +</example> +<para>If positive, the <literal>numval</literal> field identifies the number of value-instance pairs in the <literal>vlist</literal> array (despite the prototype declaration of size 1). If <literal>numval</literal> is zero, there are no values available for the associated performance metric and <literal>vlist</literal>[0] is undefined. A negative value for <literal>numval</literal> indicates an error condition (see the <command>pmErrStr(3)</command> man page) and <literal>vlist</literal>[0] is undefined. The <literal>valfmt</literal> field has the value <literal>PM_VAL_INSITU</literal> to indicate that the values for the performance metrics should be located directly via the <literal>lval</literal> member of the <literal>value</literal> union embedded in the elements of <literal>vlist</literal>; otherwise, metric values are located indirectly via the <literal>pval</literal> member of the elements of <literal>vlist</literal>.</para> +<para><indexterm id="IG31340177280"><primary>pmFetch function</primary></indexterm>The <filename>pmResult</filename> structure, as shown in <xref linkend="Z976549833sdc"/>, contains a time stamp and an array of <literal>numpmid</literal> pointers to <filename>pmValueSet</filename>.</para> +<example id="Z976549833sdc"> +<title><filename>pmResult</filename> Structure</title> +<programlisting>/* Result returned by pmFetch() */ +typedef struct { + struct timeval timestamp; /* stamped by collector */ + int numpmid; /* number of PMIDs */ + pmValueSet *vset[1]; /* set of value sets */ +} pmResult</programlisting> +</example> +<para>There is one <literal>pmValueSet</literal> pointer per PMID, with a one-to-one correspondence to the set of requested PMIDs passed to <command>pmFetch</command>.</para> +<para>Along with the metric values, the PMAPI returns a time stamp with each <filename>pmResult</filename> that serves to identify when the performance metric values were collected. The time is in the format returned by <command>gettimeofday</command> and is typically very close to the time when the metric values were extracted from their respective domains.</para> +<note><para>There is a question of exactly when individual metrics may have been collected, especially given their origin in potentially different performance metric domains, and variability in metric updating frequency by individual PMDAs. PCP uses a pragmatic approach, in which the PMAPI implementation returns all metrics with values accurate as of the time stamp, to the maximum degree possible, and PMCD demands that all PMDAs deliver values within a small realtime window. The resulting inaccuracy is small, and the additional burden of accurate individual timestamping for each returned metric value is neither warranted nor practical (from an implementation viewpoint).</para> +</note> +<para>The PMAPI provides functions to extract, rescale, and print values from the above structures; refer to <xref linkend="LE44064-PARENT"/>.</para> +</section> +<section id="id5199202"> + +<title>Performance Event Metrics</title> +<para>In addition to performance metric values which are sampled by monitor tools, +PCP supports the notion of performance event metrics which occur independently to +any sampling frequency. These event metrics (PM_TYPE_EVENT) are delivered using a +novel approach which allows both sampled and event trace data to be delivered via +the same live wire protocol, the same on-disk archive format, and fundamentally +using the same PMAPI services. In other words, a monitor tool may be sample and +trace, simultaneously, using the PMAPI services discussed here.</para> +<para>Event metrics are characterised by certain key properties, distinguishing +them from the other metric types (counters, instantaneous, and discrete):</para> +<itemizedlist> +<listitem><para>Occur at times outside of any monitor tools control, and often +have a fine-grained timestamp associated with each event. +</para></listitem> +<listitem><para>Often have parameters associated with the event, which further +describe each individual event, as shown in <xref linkend="id5198719nat"/>. +</para></listitem> +<listitem><para>May occur in very rapid succession, at rates such that both the +collector and monitor sides may not be able to track all events. This property +requires the PCP protocol to support the notion of "dropped" or "missed" events. +</para></listitem> +<listitem><para>There may be inherent relationships between events, for example +the start and commit (or rollback) of a database transaction could be separate +events, linked by a common transaction identifier (which would likely also be +one of the parameters to each event). +Begin-end and parent-child relationships are relatively common, and these +properties require the PCP protocol to support the notion of "flags" that +can be associated with events. +</para></listitem> +</itemizedlist> +<para>These differences aside, the representation of event metrics within PCP shares +many aspects of the other metric types - event metrics appear in the Name Space (as +do each of the event parameters), each has an associated Performance Metric Identifier +and Descriptor, may have an instance domain associated with them, and may be recorded +by <command>pmlogger</command> for subsequent replay.</para> +<para><figure id="id5198719nat"><title>Sample <command>write(2)</command> syscall entry point encoding</title><mediaobject><imageobject><imagedata fileref="figures/syscallevent.svg"/></imageobject><textobject><phrase>Sample syscall entry point encoding</phrase></textobject></mediaobject></figure></para> +<para>Event metrics and their associated information (parameters, timestamps, flags, +and so on) are delivered to monitoring tools alongside sampled metrics as part of the +<command>pmResult</command> structure seen previously in <xref linkend="Z976549833sdc"/>. +</para> +<para>The semantics of <command>pmFetch(3)</command> specifying an event metric PMID +are such that all events observed on the collector since the previous fetch (by this +specific monitor client) are to transfered to the monitor. Each event will have the +metadata described earlier encoded with it (timestamps, flags, and so on) for each +event. The encoding of the series of events involves a compound data structure within +the <command>pmValueSet</command> associated with the event metric PMID, as illustrated +in <xref linkend="id5198719"/>.</para> +<para><figure id="id5198719"><title>Result Format for Event Performance Metrics from <command>pmFetch</command></title><mediaobject><imageobject><imagedata fileref="figures/pmevents.svg"/></imageobject><textobject><phrase>Result Format for Event Performance Metrics from pmFetch</phrase></textobject></mediaobject></figure></para> +<para>At the highest level, the "series of events" is encapsulated within a +<command>pmEventArray</command> structure, as in <xref linkend="Z976557818nat"/>:</para> +<example id="Z976557818nat"> +<title><command>pmEventArray</command> and <command>pmEventRecord</command> Structures</title> +<programlisting>typedef struct { + __pmTimeval er_timestamp; /* 2 x 32-bit timestamp format */ + unsigned int er_flags; /* event record characteristics */ + int er_nparams; /* number of ea_param[] entries */ + pmEventParameter er_param[1]; +} pmEventRecord; + +typedef struct { + unsigned int ea_len : 24; /* bytes for type/len + records */ + unsigned int ea_type : 8; /* value type */ + int ea_nrecords; /* number of ea_record entries */ + pmEventRecord ea_record[1]; +} pmEventArray;</programlisting> +</example> +<para>Note that in the case of dropped events, the <command>pmEventRecord</command> +structure is used to convey the number of events dropped - <replaceable>er_flags</replaceable> is used to +indicate the presence of dropped events, and <replaceable>er_nparams</replaceable> is used to hold a count. +Unsurprisingly, the parameters (<replaceable>er_param</replaceable>) will be empty in this situation.</para> +<para>The <literal>pmEventParameter</literal> structure is as follows:</para> +<example id="Z1034793415nat"> +<title><literal>pmEventParameter</literal> Structure</title> +<programlisting>typedef struct { + pmID ep_pmid; /* parameter identifier */ + unsigned int ep_type; /* value type */ + int ep_len; /* bytes for type/len + vbuf */ + /* actual value (vbuf) here */ +} pmEventParameter;</programlisting> +</example> + +<section id="id5199203nat"> + +<title>Event Monitor Considerations</title> +<para><indexterm id="IG31340177280nat"><primary>pmUnpackEventRecords function</primary></indexterm>In order to simplify +the decoding of event record arrays, the PMAPI provides the <command>pmUnpackEventRecords</command> function +for monitor tools. This function is passed a pointer to a <command>pmValueSet</command> associated with an event +metric (within a <command>pmResult</command>) from a <command>pmFetch(3)</command>. For a given instance of +that event metric, it returns an array of "unpacked" <command>pmResult</command> structures for each event.</para> +<para>The control information (flags and optionally dropped events) is included as derived metrics +within each result structure. As such, these values can be queried similarly to other metrics, using +their names - <literal>event.flags</literal> and <literal>event.missed</literal>. Note that these +metrics will only exist after the first call to <command>pmUnpackEventRecords</command>.</para> +<para>An example of decoding event metrics in this way is presented in <xref linkend="Z976557819nat"/>:</para> +<example id="Z976557819nat"> +<title>Unpacking Event Records from an Event Metric <literal>pmValueSet</literal></title> +<programlisting>enum { event_flags = 0, event_missed = 1 }; +static char *metadata[] = { "event.flags", "event.missed" }; +static pmID metapmid[2]; + +void dump_event(pmValueSet *vsp, int idx) +{ + pmResult **res; + int r, sts, nrecords; + + nrecords = pmUnpackEventRecords(vsp, idx, &res); + if (nrecords < 0) + fprintf(stderr, " pmUnpackEventRecords: %s\n", pmErrStr(nrecords)); + else + printf(" %d event records\n", nrecords); + + if ((sts = pmLookupName(2, &metadata, &metapmid)) < 0) { + fprintf(stderr, "Event metadata error: %s\n", pmErrStr(sts)); + exit(1); + } + + for (r = 0; r < nrecords; r++) + dump_event_record(res, r); + + if (nrecords >= 0) + pmFreeEventResult(res); +} + +void dump_event_record(pmResult *res, int r) +{ + int p; + + __pmPrintStamp(stdout, &res[r]->timestamp); + if (res[r]->numpmid == 0) + printf(" ==> No parameters\n"); + for (p = 0; p < res[r]->numpmid; p++) { + pmValueSet *vsp = res[r]->vset[p]; + + if (vsp->numval < 0) { + int error = vsp->numval; + printf("%s: %s\n", pmIDStr(vsp->pmid), pmErrStr(error)); + } else if (vsp->pmid == metapmid[event_flags]) { + int flags = vsp->vlist[0].value.lval; + printf(" flags 0x%x (%s)\n", flags, pmEventFlagsStr(flags)); + } else if (vsp->pmid == metapmid[event_missed]) { + int count = vsp->vlist[0].value.lval; + printf(" ==> %d missed event records\n", count); + } else { + dump_event_record_parameters(vsp); + } + } +} + +void dump_event_record_parameters(pmValueSet *vsp) +{ + pmDesc desc; + char *name; + int sts, j; + + if ((sts = pmLookupDesc(vsp->pmid, &desc)) < 0) { + fprintf(stderr, "pmLookupDesc: %s\n", pmErrStr(sts)); + } else + if ((sts = pmNameID(vsp->pmid, &name)) < 0) { + fprintf(stderr, "pmNameID: %s\n", pmErrStr(sts)); + } else { + printf("parameter %s", name); + for (j = 0; j < vsp->numval; j++) { + pmValue *vp = &vsp->vlist[j]; + if (vsp->numval > 1) { + printf("[%d]", vp->inst); + pmPrintValue(stdout, vsp->valfmt, desc.type, vp, 1); + putchar('\n'); + } + } + free(name); + } +}</programlisting> +</example> + +</section> +<section id="id5199204nat"> + +<title>Event Collector Considerations</title> +<para>There is a feedback mechanism that is inherent in the design of the PCP +monitor-collector event metric value exchange, which protects both monitor +and collector components from becoming overrun by high frequency event arrivals. +It is important that PMDA developers are aware of this mechanism and all of +its implications.</para> +<para>Monitor tools can query new event arrival on whatever schedule they +choose. There are no guarantees that this is a fixed interval, and no way +for the PMDA to attempt to dictate this interval (nor should there be).</para> +<para>As a result, a PMDA that provides event metrics must:</para> +<itemizedlist> +<listitem><para>Track individual client connections using the per-client PMDA +extensions (PMDA_INTERFACE_5 or later).</para> +</listitem> +<listitem><para>Queue events, preferably in a memory-efficient manner, such +that each interested monitor tool (there may be more than one) is informed +of those events that arrived since their last request.</para> +</listitem> +<listitem><para>Control the memory allocated to in-memory event storage. +If monitors are requesting new events too slowly, compared to event arrival +on the collector, the "missed events" feedback mechanism must be used to +inform the monitor. +This mechanism is also part of the model by which a PMDA can fix the amount +of memory it uses. Once a fixed space is consumed, events can be dropped +from the tail of the queue for each client, provided a counter is incremented +and the client is subsequently informed.</para> +</listitem> +</itemizedlist> +<note><para>It is important that PMDAs are part of the performance solution, +and not part of the performance problem! With event metrics, this is much +more difficult to achieve than with counters or other sampled values.</para></note> + +<para>There is certainly elegance to this approach for event metrics, and +the way they dovetail with other, sampled performance metrics is unique to +PCP. Notice also how the scheme naturally allows multiple monitor tools to +consume the same events, no matter what the source of events is. +The downside to this flexibility is increased complexity in the PMDA when +event metrics are used.</para> +<para>This complexity comes in the form of event queueing and memory +management, as well as per-client state tracking. Routines are available as +part of the <command>pcp_pmda</command> library to assist, however - refer +to the man page entries for <command>pmdaEventNewQueue(3)</command> and +<command>pmdaEventNewClient(3)</command> for further details.</para> + +<para>One final set of helper APIs is available to PMDA developers who +incorporate event metrics. +There is a need to build the <command>pmEventArray</command> structure, +introduced in <xref linkend="Z976557818nat"/>. This can be done directly, +or using the helper routine <command>pmdaEventNewArray(3)</command>. +If the latter, simpler model is chosen, the closely related routines +<command>pmdaEventAddRecord</command>, <command>pmdaEventAddParam</command> +and <command>pmdaEventAddMissedRecord</command> would also usually be used.</para> + +<para>Depending on the nature of the events being exported by a PMDA, it +can be desirable to perform <emphasis role="bold">filtering</emphasis> +of events on the collector system. This reduces the amount of event traffic +between monitor and collector systems (which may be filtered further on the +monitor system, before presenting results). Some PMDAs have had success using +the <command>pmStore(3)</command> mechanism to allow monitor tools to send a +filter to the PMDA - using either a special control metric for the store +operation, or the event metric itself. The filter sent will depend on the +event metric, but it might be a regular expression, or a tracing script, +or something else.</para> +<para>This technique has also been used to <emphasis role="bold">enable</emphasis> +and <emphasis role="bold">disable</emphasis> event tracing entirely. It is often +appropriate to make use of authentication and user credentials when providing +such a facility (PMDA_INTERFACE_6 or later).</para> +</section> +</section> +<section id="id5199203"> + +<title>PMAPI Programming Style and Interaction</title> +<para><indexterm id="IG31340177281"><primary>PMAPI</primary><secondary>programming style</secondary></indexterm>The following sections describe the PMAPI programming style:</para> +<itemizedlist> +<listitem><para>Variable length argument and results lists</para> +</listitem> +<listitem><para>Python specific issues</para> +</listitem> +<listitem><para>PMAPI error handling</para> +</listitem></itemizedlist> +<section id="LE37655-PARENT"> + +<title>Variable Length Argument and Results Lists</title> +<para><indexterm id="IG31340177282"><primary>PMAPI</primary><secondary>variable length arguments</secondary></indexterm><indexterm id="IG31340177283"><primary>arrays</primary><secondary>performance metrics</secondary></indexterm>All arguments and results involving a “list of something” are encoded as an array with an associated argument or function value to identify the number of elements in the array. This encoding scheme avoids both the <literal>varargs</literal> approach and sentinel-terminated lists. Where the size of a result is known at the time of a call, it is the caller's responsibility to allocate (and possibly free) the storage, and the called function assumes that the resulting argument is of an appropriate size.</para> +<para><indexterm id="IG31340177284"><primary>pmNameInDom function</primary></indexterm><indexterm id="IG31340177285"><primary>pmLookupText function</primary></indexterm><indexterm id="IG31340177286"><primary>pmGetInDom function</primary></indexterm><indexterm id="IG31340177287"><primary>pmNameID function</primary></indexterm><indexterm id="IG31340177288"><primary>pmGetChildren function</primary></indexterm><indexterm id="IG31340177289"><primary>pmFetch function</primary></indexterm><indexterm id="IG31340177290"><primary>pmFreeResult function</primary></indexterm>Where a result is of variable size and that size cannot be known in advance (for example, <command>pmGetChildren</command>, <command>pmGetInDom</command>, <command>pmNameInDom</command>, <command>pmNameID</command>, <command>pmLookupText</command>, and <command>pmFetch</command>), the underlying implementation uses dynamic allocation through <command>malloc</command> +in the called function, with the caller responsible for subsequently calling <command>free</command> to release the storage when no longer required. In the case of the result from <command>pmFetch</command>, there is a function (<command>pmFreeResult</command>) to release the storage, due to the complexity of the data structure and the need to make multiple calls to <command>free</command> in the correct sequence. As a general rule, if the called function returns an error status, then no allocation is done, the pointer to the variable sized result is undefined, and <command>free</command> or <command>pmFreeResult</command> should not be called.</para> +</section> + +<section> + +<title>Python Specific Issues</title> +<para><indexterm id="python-issues"><primary>PMAPI</primary><secondary>python issues</secondary></indexterm> +A pcp client may be written in the python language by making use of the python bindings for PMAPI. The bindings use the python ctypes module to provide an interface to the PMAPI C language data structures. The primary imports that are needed by a client are: +<itemizedlist> +<listitem><para>cpmapi which provides access to PMAPI constants +<programlisting>import cpmapi as c_api</programlisting></para></listitem> +<listitem><para>pmapi which provides access to PMAPI functions and data structures +<programlisting>from pcp import pmapi</programlisting></para></listitem> +<listitem><para>pmErr which provides access to the python bindings exception handler +<programlisting>from pcp.pmapi import pmErr</programlisting></para></listitem> +<listitem><para>pmgui which provides access to PMAPI record mode functions +<programlisting>from pcp import ppmgui</programlisting></para></listitem> +</itemizedlist> +Creating and destroying a PMAPI context in the python environment is done by creating and destroying an object of the pmapi class. This is done in one of two ways, either directly: +<programlisting> context = pmapi.pmContext()</programlisting> +or by automated processing of the command line arguments (refer to the <command>pmGetOptions</command> man page for greater detail). +<programlisting> options = pmapi.pmOptions(...) + context = pmapi.pmContext.fromOptions(options, sys.argv)</programlisting> +Most PMAPI C functions have python equivalents with similar, although +not identical, call signatures. Some of the python functions do not +return native python types, but instead return native C types wrapped +by the ctypes library. In most cases these types are opaque, or +nearly so; for example <replaceable>pmid</replaceable>: +<programlisting> pmid = context.pmLookupName("mem.freemem") + desc = context.pmLookupDescs(pmid) + result = context.pmFetch(pmid) + ...</programlisting> +See the comparison of a standalone C and python client application in <xref linkend="id5212839"/>. +</para> +</section> + +<section id="LE62826-PARENT"> + +<title>PMAPI Error Handling</title> +<para><indexterm id="IG31340177291"><primary>PMAPI</primary><secondary>error handling</secondary></indexterm>Where error conditions may arise, the functions that compose the PMAPI conform to a single, simple error notification scheme, as follows:</para> +<itemizedlist> +<listitem><para>The function returns an <literal>int</literal>. Values greater than or equal to zero indicate no error, and perhaps some positive status: for example, the number of items processed.</para> +</listitem> +<listitem><para>Values less than zero indicate an error, as determined by a global table of error conditions and messages.</para> +</listitem></itemizedlist> +<para>A PMAPI library function along the lines of <command>strerror</command> is provided to translate error conditions into error messages; see the <command>pmErrStr(3)</command> and <command>pmErrStr_r(3)</command> man pages. The error condition is returned as the function value from a previous PMAPI call; there is no global error indicator (unlike <literal>errno</literal>). This is to accommodate multi-threaded performance tools.</para> +<para>The available error codes may be displayed with the following command:</para> +<programlisting><userinput>pmerr -l</userinput></programlisting> +<para>Where possible, PMAPI routines are made as tolerant to failure as possible. In particular, routines which deal with compound data structures - results structures, multiple name lookups in one call and so on, will attempt to return all data that can be returned successfully, and errors embedded in the result where there were (partial) failures. In such cases a negative failure return code from the routine indicates catastrophic failure, otherwise success is returned and indicators for the partial failures are returned embedded in the results.</para> +</section> +</section> +<section id="id5199561"> + +<title>PMAPI Procedural Interface</title> +<para>The following sections describe all of the PMAPI functions that provide access to the PCP infrastructure on behalf of a client application:</para> +<itemizedlist> +<listitem><para>PMAPI Name Space services</para> +</listitem> +<listitem><para>PMAPI metric description services</para> +</listitem> +<listitem><para>PMAPI instance domain services</para> +</listitem> +<listitem><para>PMAPI context services</para> +</listitem> +<listitem><para>PMAPI timezone services</para> +</listitem> +<listitem><para>PMAPI metrics services</para> +</listitem> +<listitem><para>PMAPI record-mode services</para> +</listitem> +<listitem><para>PMAPI archive-specific services</para> +</listitem> +<listitem><para>PMAPI time control services</para> +</listitem> +<listitem><para>PMAPI ancillary support services</para> +</listitem></itemizedlist> +<section id="LE32034-PARENT"> + +<title>PMAPI Name Space Services</title> +<para>The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) Name Space services.</para> +<section id="id5199677"> + +<title><command>pmGetChildren</command> Function</title> +<literallayout class="monospaced">int pmGetChildren(const char*<replaceable>name</replaceable>, char***<replaceable>offspring</replaceable>) +<command>Python:</command> +[name1, name2...] = pmGetChildren(<replaceable>name</replaceable>)</literallayout> +<para><indexterm id="IG31340177292"><primary>PMAPI</primary><secondary>Name Space services</secondary></indexterm><indexterm id="IG31340177293"><primary>pmGetChildren function</primary></indexterm>Given a full pathname to a node in the current PMNS, as identified by <replaceable>name</replaceable>, return through <replaceable>offspring</replaceable> a list of the relative names of all the immediate descendents of <replaceable>name</replaceable> in the current PMNS. As a special case, if <replaceable>name</replaceable> is an empty string, (that is, <literal>""</literal> but not <literal>NULL</literal> or <literal>(char *)0</literal>), the immediate descendents of the root node in the PMNS are returned.</para> + +<para>For the python bindings a tuple containing the relative names of all the immediate descendents of <replaceable>name</replaceable> in the current PMNS is returned. +</para> +<para>Normally, <command>pmGetChildren</command> returns the number of descendent names discovered, or a value less than zero for an error. The value zero indicates that the <replaceable>name</replaceable> is valid, and associated with a leaf node in the PMNS.</para> +<para>The resulting list of pointers (<replaceable>offspring</replaceable>) and the values (relative metric names) that the pointers reference are allocated by <command>pmGetChildren</command> with a single call to <command>malloc</command>, and it is the responsibility of the caller to issue a <command>free</command><replaceable>(offspring)</replaceable> system call to release the space when it is no longer required. When the result of <command>pmGetChildren</command> is less than one, <replaceable>offspring</replaceable> is undefined (no space is allocated, and so calling <command>free</command> is counterproductive).</para> + +<para>The python bindings return a tuple containing the relative names of all the immediate descendents of <replaceable>name</replaceable>, where <replaceable>name</replaceable> is a full pathname to a node in the current PMNS.</para> +</section> +<section id="id5199872"> + +<title><command>pmGetChildrenStatus</command> Function</title> +<literallayout class="monospaced">int pmGetChildrenStatus(const char *<replaceable>name</replaceable>, char ***<replaceable>offspring</replaceable>, int **<replaceable>status</replaceable>) +<command>Python:</command> +([name1, name2...],[status1, status2...]) = pmGetChildrenStatus(<replaceable>name</replaceable>)</literallayout> +<para><indexterm id="IG31340177294"><primary>pmGetChildren function</primary></indexterm>The <command>pmGetChildrenStatus</command> function is an extension of <command>pmGetChildren</command> that optionally returns status information about each of the descendent names.</para> +<para>Given a fully qualified pathname to a node in the current PMNS, as identified by <replaceable>name</replaceable>, <command>pmGetChildrenStatus</command> returns by means of <replaceable>offspring</replaceable> a list of the relative names of all of the immediate descendent nodes of <replaceable>name</replaceable> in the current PMNS. If <replaceable>name</replaceable> is the empty string (””), it returns the immediate descendents of the root node in the PMNS.</para> +<para>If <replaceable>status</replaceable> is not NULL, then <command>pmGetChildrenStatus</command> also returns the status of each child by means of <replaceable>status</replaceable>. This refers to either a leaf node (with value <literal>PMNS_LEAF_STATUS</literal>) or a non-leaf node (with value <literal>PMNS_NONLEAF_STATUS</literal>).</para> +<para>Normally, <command>pmGetChildrenStatus</command> returns the number of descendent names discovered, or else a value less than zero to indicate an error. The value zero indicates that name is a valid metric name, being associated with a leaf node in the PMNS.</para> +<para>The resulting list of pointers (<replaceable>offspring</replaceable>) and the values (relative metric names) that the pointers reference are allocated by <command>pmGetChildrenStatus</command> with a single call to <command>malloc</command>, and it is the responsibility of the caller to <command>free</command>(<replaceable>offspring</replaceable>) to release the space when it is no longer required. The same holds true for the <replaceable>status</replaceable> array.</para> + +<para>The python bindings return a tuple containing the relative names and statuses of all the immediate descendents of <replaceable>name</replaceable>, where <replaceable>name</replaceable> is a full pathname to a node in the current PMNS.</para> +</section> +<section id="id5200032"> + +<title><command>pmGetPMNSLocation</command> Function</title> +<literallayout class="monospaced">int pmGetPMNSLocation(void) +<command>Python:</command> +int loc = pmGetPMNSLocation()</literallayout> +<para><indexterm id="IG31340177295"><primary>pmGetPMNSLocation function</primary></indexterm>If an application needs to know where the origin of a PMNS is, <command>pmGetPMNSLocation</command> returns whether it is an archive (<filename>PMNS_ARCHIVE</filename>), a local PMNS file (<filename>PMNS_LOCAL</filename>), or a remote PMCD (<filename>PMNS_REMOTE</filename>). This information may be useful in determining an appropriate error message depending on PMNS location.</para> + +<para>The python bindings return whether a PMNS is an archive <replaceable>cpmapi.PMNS_ARCHIVE</replaceable>, a local PMNS file <replaceable>cpmapi.PMNS_LOCAL</replaceable>, or a remote PMCD <replaceable>cpmapi.PMNS_REMOTE</replaceable>. The constants are available by importing cpmapi.</para> +</section> +<section id="id5200074"> + +<title><command>pmLoadNameSpace</command> Function</title> +<literallayout class="monospaced">int pmLoadNameSpace(const char *<replaceable>filename</replaceable>) +<command>Python:</command> +int <replaceable>status</replaceable> = pmLoadNameSpace(<replaceable>filename</replaceable>)</literallayout> +<para><indexterm id="IG31340177296"><primary>pmLoadNameSpace function</primary></indexterm>In the highly unusual situation that an application wants to force using a local Performance Metrics Name Space (PMNS), the application can load the PMNS using <command>pmLoadNameSpace</command>.</para> +<para>The <replaceable>filename</replaceable> argument designates the PMNS of interest. For applications that do not require a tailored Name Space, the special value <literal>PM_NS_DEFAULT</literal> may be used for <replaceable>filename</replaceable>, to force a default local PMNS to be established. Externally, a PMNS is stored in an ASCII format.</para> +<para>The python bindings load a local tailored Name Space from <replaceable>filename</replaceable>. </para> +<note><para>Do not use this routine in monitor tools. The distributed PMNS services avoid the need for a local PMNS; so applications should <emphasis role="bold">not</emphasis> use <command>pmLoadNameSpace</command>. Without this call, the default PMNS is the one at the source of the performance metrics (PMCD or an archive).</para> +</note> +</section> +<section id="id5200342"> + +<title><command>pmLookupName</command> Function</title> +<literallayout class="monospaced">int pmLookupName(int <replaceable>numpmid</replaceable>, char *<replaceable>namelist</replaceable>[], pmID <replaceable>pmidlist</replaceable>[]) +<command>Python:</command> +c_uint <replaceable>pmid</replaceable> [] = pmLookupName(<replaceable>"MetricName"</replaceable>) +c_uint <replaceable>pmid</replaceable> [] = pmLookupName((<replaceable>"MetricName1"</replaceable>, <replaceable>"MetricName2"</replaceable>, ...))</literallayout> +<para><indexterm id="IG31340177298"><primary>pmLookupName function</primary></indexterm>Given a list in <replaceable>namelist</replaceable> containing <replaceable>numpmid</replaceable> full pathnames for performance metrics from the current PMNS, <command>pmLookupName</command> returns the list of associated PMIDs through the <replaceable>pmidlist</replaceable> parameter. Invalid metrics names are translated to the error PMID value of <literal>PM_ID_NULL</literal>.</para> +<para>The result from <command>pmLookupName</command> is the number of names translated in the absence of errors, or an error indication. Note that argument definition and the error protocol guarantee a one-to-one relationship between the elements of <replaceable>namelist</replaceable> and <replaceable>pmidlist</replaceable>; both lists contain exactly <replaceable>numpmid</replaceable> elements.</para> +<para>The python bindings return an array of associated PMIDs corresponding to a tuple of <replaceable>MetricNames</replaceable>. The returned <replaceable>pmid</replaceable> tuple is passed to <command>pmLookupDescs</command> and <command>pmFetch</command>.</para> +</section> +<section id="id5200423"> + +<title><command>pmNameAll</command> Function</title> +<literallayout class="monospaced">int pmNameAll(pmID <replaceable>pmid</replaceable>, char ***<replaceable>nameset</replaceable>) +<command>Python:</command> +[name1, name2...] = pmNameAll(<replaceable>pmid</replaceable>)</literallayout> +<para><indexterm id="IG31340177299"><primary>pmNameAll function</primary></indexterm>Given a performance metric ID in <replaceable>pmid</replaceable>, <command>pmNameAll</command> determines all the corresponding metric names, if any, in the PMNS, and returns these through <replaceable>nameset</replaceable>.</para> +<para>The resulting list of pointers <replaceable>nameset</replaceable> and the values (relative names) that the pointers reference are allocated by <command>pmNameAll</command> with a single call to <command>malloc</command>. It is the caller's responsibility to call <command>free</command> and release the space when it is no longer required.</para> +<para>In the absence of errors, <command>pmNameAll</command> returns the number of names in <command>nameset</command>.</para> +<para>For many PMNS instances, there is a 1:1 mapping between a name and a PMID, and under these circumstances, <command>pmNameID</command> provides a simpler interface in the absence of duplicate names for a particular PMID.</para> +<para>The python bindings return a tuple of all metric names having this identical <replaceable>pmid</replaceable>.</para> +</section> +<section id="id5200532"> + +<title><command>pmNameID</command> Function</title> +<literallayout class="monospaced">int pmNameID(pmID <replaceable>pmid</replaceable>, char **<replaceable>name</replaceable>) +<command>Python:</command> +"metric name" = pmNameID(<replaceable>pmid</replaceable>)</literallayout> +<para><indexterm id="IG31340177300"><primary>pmNameID function</primary></indexterm>Given a performance metric ID in <replaceable>pmid</replaceable>, <command>pmNameID</command> determines the corresponding metric name, if any, in the current PMNS, and returns this through <replaceable>name</replaceable>.</para> +<para>In the absence of errors, <command>pmNameID</command> returns zero. The <replaceable>name</replaceable> argument is a null byte terminated string, allocated by <command>pmNameID</command> using <command>malloc</command>. It is the caller's responsibility to call <command>free</command> and release the space when it is no longer required.</para> +<para>The python bindings return a metric name corresponding to a <replaceable>pmid</replaceable>.</para> +</section> +<section id="id5200683"> + +<title><command>pmTraversePMNS</command> Function</title> +<literallayout class="monospaced">int pmTraversePMNS(const char *<replaceable>name</replaceable>, void (*<command>dometric</command>)(const char *)) +<command>Python:</command> +int <replaceable>status</replaceable> = pmTraversePMNS(<replaceable>name</replaceable>, <replaceable>traverse_callback</replaceable>)</literallayout> +<para><indexterm id="IG31340177301"><primary>pmTraversePMNS function</primary></indexterm>The function <command>pmTraversePMNS</command> may be used to perform a depth-first traversal of the PMNS. The traversal starts at the node identified by <replaceable>name</replaceable> --if <replaceable>name</replaceable> is an empty string, the traversal starts at the root of the PMNS. Usually, <replaceable>name</replaceable> would be the pathname of a non-leaf node in the PMNS.</para> +<para><indexterm id="IG31340177302"><primary>dometric function</primary></indexterm><indexterm id="IG31340177303"><primary>leaf node</primary></indexterm>For each leaf node (actual performance metrics) found in the traversal, the user-supplied function <command>dometric</command> is called with the full pathname of that metric in the PMNS as the single argument; this argument is a null byte-terminated string, and is constructed from a buffer that is managed internally to <command>pmTraversePMNS</command>. Consequently, the value is valid only during the call to <command>dometric</command>--if the pathname needs to be retained, it should be copied using <command>strdup</command> before returning from <command>dometric</command>; see the <command>strdup(3)</command> man page.</para> +<para>The python bindings perform a depth first traversal of the PMNS by scanning <replaceable>namespace</replaceable>, depth first, and call a python function <replaceable>traverse_callback</replaceable> for each node. +</para> +</section> +<section id="id5200806"> + +<title><command>pmUnloadNameSpace</command> Function</title> +<literallayout class="monospaced">int pmUnloadNameSpace(void) +<command>Python:</command> +pmUnLoadNameSpace(<replaceable>"NameSpace"</replaceable>)</literallayout> +<para><indexterm id="IG31340177304"><primary>pmUnloadNameSpace function</primary></indexterm>If a local PMNS was loaded with <command>pmLoadNameSpace</command>, calling <command>pmUnloadNameSpace</command> frees up the memory associated with the PMNS and force all subsequent Name Space functions to use the distributed PMNS. If <command>pmUnloadNameSpace</command> is called before calling <command>pmLoadNameSpace</command>, it has no effect.</para> +<para>As discussed in <xref linkend="id5200074"/> there are few if any situations where clients need to call this routine in modern versions of PCP.</para> +</section> +</section> +<section id="LE89521-PARENT"> + +<title>PMAPI Metrics Description Services</title> +<para>The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) metric description services.</para> +<section id="id5200868"> + +<title><command>pmLookupDesc</command> Function</title> +<literallayout class="monospaced">int pmLookupDesc(pmID <replaceable>pmid</replaceable>, pmDesc *<replaceable>desc</replaceable>) +<command>Python:</command> +pmDesc* <replaceable>pmdesc</replaceable> = pmLookupDesc(c_uint <replaceable>pmid</replaceable>) +(pmDesc* <replaceable>pmdesc</replaceable>)[] = pmLookupDescs(c_uint <replaceable>pmids</replaceable>[N]) +(pmDesc* <replaceable>pmdesc</replaceable>)[] = pmLookupDescs(c_uint <replaceable>pmid</replaceable>)</literallayout> +<para><indexterm id="IG31340177305"><primary>metrics description services</primary></indexterm><indexterm id="IG31340177306"><primary>metric description services</primary></indexterm><indexterm id="IG31340177307"><primary>pmLookupDesc function</primary></indexterm><indexterm id="IG31340177308"><primary>PMAPI</primary><secondary>description services</secondary></indexterm>Given a Performance Metric Identifier (PMID) as <replaceable>pmid</replaceable>, <command>pmLookupDesc</command> returns the associated <literal>pmDesc</literal> structure through the parameter <replaceable>desc</replaceable> from the current PMAPI context. For more information about <literal>pmDesc</literal>, see <xref linkend="LE11914-PARENT"/>.</para> +<para> +The python bindings return the metric description structure <literal>pmDesc</literal> corresponding to <replaceable>pmid</replaceable>. The returned <replaceable>pmdesc</replaceable> is passed to <command>pmExtractValue</command> and <command>pmLookupInDom</command>. The python bindings provide an entry <command>pmLookupDescs</command> that is similar to pmLookupDesc but does a metric description lookup for each element in a PMID array <replaceable>pmids</replaceable>.</para> +</section> +<section id="id5200999"> + +<title><command>pmLookupInDomText</command> Function</title> +<programlisting>int pmLookupInDomText(pmInDom <replaceable>indom</replaceable>, int <replaceable>level</replaceable>, char **<replaceable>buffer</replaceable>) +<command>Python:</command> +"metric description" = pmGetInDomText(pmDesc <replaceable>pmdesc</replaceable>)</programlisting> +<para><indexterm id="IG31340177309"><primary>indom instance domain</primary></indexterm><indexterm id="IG31340177310"><primary>pmLookupInDomText function</primary></indexterm>Provided the source of metrics from the current PMAPI context is a host, retrieve descriptive text about the performance metrics instance domain identified by <replaceable>indom</replaceable>.</para> +<para><indexterm id="IG31340177311"><primary>help text</primary><secondary>pmLookupInDomText function</secondary></indexterm>The <replaceable>level</replaceable> argument should be <literal>PM_TEXT_ONELINE</literal> for a one-line summary, or <literal>PM_TEXT_HELP</literal> for a more verbose description suited to a help dialogue. The space pointed to by <replaceable>buffer</replaceable> is allocated in <command>pmLookupInDomText</command> with <command>malloc</command>, and it is the responsibility of the caller to free unneeded space; see the <command>malloc(3)</command> and<command> free(3)</command> man pages.</para> +<para>The help text files used to implement <filename>pmLookupInDomText</filename> are often created using <command>newhelp</command> and accessed by the appropriate PMDA response to requests forwarded to the PMDA by PMCD. Further details may be found in <xref linkend="LE72473-PARENT"/>.</para> +<para> +The python bindings lookup the description text about the performance metrics pmDesc <replaceable>pmdesc</replaceable>. The default is a one line summary; for a more verbose description add an optional second parameter <replaceable>cpmapi.PM_TEXT_HELP</replaceable>. The constant is available by importing cpmapi. +</para> +</section> +<section id="id5201140"> + +<title><command>pmLookupText</command> Function</title> +<programlisting>int pmLookupText(pmID <replaceable>pmid</replaceable>, int <replaceable>level</replaceable>, char **<replaceable>buffer</replaceable>) +<command>Python:</command> +"metric description" = pmLookupText(c_uint <replaceable>pmid</replaceable>)</programlisting> +<para><indexterm id="IG31340177312"><primary>pmLookupText function</primary></indexterm><indexterm id="IG31340177313"><primary>help text</primary><secondary>pmLookupText function</secondary></indexterm>Provided the source of metrics from the current PMAPI context is a host, retrieve descriptive text about the performance metric identified by <replaceable>pmid</replaceable>. The argument <replaceable>level</replaceable> should be <literal>PM_TEXT_ONELINE</literal> for a one-line summary, or <literal>PM_TEXT_HELP</literal> for a more verbose description, suited to a help dialogue.</para> +<para>The space pointed to by <replaceable>buffer</replaceable> is allocated in <command>pmLookupText</command> with <command>malloc</command>, and it is the responsibility of the caller to <command>free</command> the space when it is no longer required; see the <command>malloc(3)</command> and <command>free(3)</command> man pages.</para> +<para>The help text files used to implement <command>pmLookupText</command> are created using <command>newhelp</command> and accessed by the appropriate PMDA in response to requests forwarded to the PMDA by PMCD. Further details may be found in <xref linkend="LE72473-PARENT"/>.</para> +<para> +The python bindings lookup the description text about the performance metrics pmID <replaceable>pmid</replaceable>. The default is a one line summary; for a more verbose description add an optional second parameter <replaceable>cpmapi.PM_TEXT_HELP</replaceable>. The constant is available by importing cpmapi. +</para> +</section> +</section> +<section id="LE27200-PARENT"> + +<title>PMAPI Instance Domain Services</title> +<para>The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) instance domain services.</para> +<section id="id5201278"> + +<title><command>pmGetInDom</command> Function</title> +<literallayout class="monospaced">int pmGetInDom(pmInDom <replaceable>indom</replaceable>, int **<replaceable>instlist</replaceable>, char ***<replaceable>namelist</replaceable>) +<command>Python:</command> +([instance1, instance2...] [name1, name2...]) pmGetInDom(pmDesc <replaceable>pmdesc</replaceable>)</literallayout> +<para><indexterm id="IG31340177314"><primary>instance domain services</primary></indexterm><indexterm id="IG31340177315"><primary>instlist argument</primary></indexterm><indexterm id="IG31340177316"><primary>pmGetInDom function</primary></indexterm><indexterm id="IG31340177317"><primary>PMAPI</primary><secondary>instance domain services</secondary></indexterm>In the current PMAPI context, locate the description of the instance domain <replaceable>indom</replaceable>, and return through <replaceable>instlist</replaceable> the internal instance identifiers for all instances, and through <replaceable>namelist</replaceable> the full external identifiers for all instances. The number of instances found is returned as the function value (or less than zero to indicate an error).</para> +<para>The resulting lists of instance identifiers (<replaceable>instlist</replaceable> and <replaceable>namelist</replaceable>), and the names that the elements of <replaceable>namelist</replaceable> point to, are allocated by <command>pmGetInDom</command> with two calls to <command>malloc</command>, and it is the responsibility of the caller to use <command>free</command><replaceable>(instlist)</replaceable> and <command>free</command><replaceable>(namelist) </replaceable>to release the space when it is no longer required. When the result of <command>pmGetInDom</command> is less than one, both <replaceable>instlist</replaceable> and <replaceable>namelist</replaceable> are undefined (no space is allocated, and so calling <command>free</command> is a bad idea); see the <command> +malloc(3)</command> and <command>free(3)</command> man pages.</para> +<para> +The python bindings return a tuple of the instance identifiers and instance names for an instance domain <replaceable>pmdesc</replaceable>. </para> +</section> +<section id="id5201511"> + +<title><command>pmLookupInDom</command> Function</title> +<programlisting>int pmLookupInDom(pmInDom <replaceable>indom</replaceable>, const char *<replaceable>name</replaceable>) +<command>Python:</command> +int <replaceable>instid</replaceable> = pmLookupInDom(pmDesc <replaceable>pmdesc</replaceable>, <replaceable>"Instance"</replaceable>)</programlisting> +<para><indexterm id="IG31340177318"><primary>pmLookupInDom function</primary></indexterm>For the instance domain <replaceable>indom</replaceable>, in the current PMAPI context, locate the instance with the external identification given by <replaceable>name</replaceable>, and return the internal instance identifier.</para> +<para> +The python bindings return the instance id corresponding to <replaceable>"Instance"</replaceable> in the instance domain <replaceable>pmdesc</replaceable>. +</para> +</section> +<section id="id5201553"> + +<title><command>pmNameInDom</command> Function</title> +<programlisting>int pmNameInDom(pmInDom <replaceable>indom</replaceable>, int <replaceable>inst</replaceable>, char **<replaceable>name</replaceable>) +<command>Python:</command> +"instance id" = pmNameInDom(pmDesc <replaceable>pmdesc</replaceable>, c_uint <replaceable>instid</replaceable>)</programlisting> +<para><indexterm id="IG31340177319"><primary>pmNameInDom function</primary></indexterm>For the instance domain <replaceable>indom</replaceable>, in the current PMAPI context, locate the instance with the internal instance identifier given by <replaceable>inst</replaceable>, and return the full external identification through <replaceable>name</replaceable>. The space for the value of <replaceable>name</replaceable> is allocated in <command>pmNameInDom</command> with <command>malloc</command>, and it is the responsibility of the caller to free the space when it is no longer required; see the <command>malloc(3)</command> and <command>free(3)</command> man pages.</para> +<para> +The python bindings return the text name of an instance corresponding to an instance domain <replaceable>pmdesc</replaceable> with instance identifier <replaceable>instid</replaceable>. +</para> +</section> +</section> +<section id="LE94187-PARENT"> + +<title>PMAPI Context Services</title> +<para><indexterm id="IG31340177320"><primary>context services</primary></indexterm><indexterm id="IG31340177321"><primary>PMAPI</primary><secondary>context services</secondary></indexterm><xref linkend="id5201726"/> shows which of the three components of a PMAPI context (metrics source, instance profile, and collection time) are relevant for various PMAPI functions. Those PMAPI functions not shown in this table either manipulate the PMAPI context directly, or are executed independently of the current PMAPI context.</para> +<table id="id5201726" frame="topbot"> + +<title>Context Components of PMAPI Functions </title> +<tgroup cols="5" colsep="0" rowsep="0"> +<colspec colwidth="132*"/> +<colspec colwidth="75*"/> +<colspec colwidth="77*"/> +<colspec colwidth="77*"/> +<colspec colwidth="35*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Function Name</para></entry><entry align="left" valign="bottom"><para>Metrics Source</para></entry><entry align="left" valign="bottom"><para>Instance Profile</para></entry><entry align="left" valign="bottom"><para>Collection Time</para></entry><entry align="left" valign="bottom"><para>Notes</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmAddProfile</command><indexterm id="IG31340177322"><primary>pmAddProfile function</primary></indexterm></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmDelProfile<indexterm id="IG31340177323"><primary>pmDelProfile function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmDupContext<indexterm id="IG31340177324"><primary>pmDupContext function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmFetch<indexterm id="IG31340177325"><primary>pmFetch function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmFetchArchive<indexterm id="IG31340177326"><primary>pmFetchArchive function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>(1)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmGetArchiveEnd<indexterm id="IG31340177327"><primary>pmGetArchiveEnd function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(1)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmGetArchiveLabel<indexterm id="IG31340177328"><primary>pmGetArchiveLabel function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(1)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmGetChildren<indexterm id="IG31340177329"><primary>pmGetChildren function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmGetChildrenStatus<indexterm id="IG31340177330"><primary>pmGetChildrenStatus function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmGetContextHostName<indexterm id="IG31340177330nat"><primary>pmGetContextHostName function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmGetPMNSLocation<indexterm id="IG31340177331"><primary>pmGetPMNSLocation function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmGetInDom<indexterm id="IG31340177332"><primary>pmGetInDom function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>(2)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmGetInDomArchive<indexterm id="IG31340177333"><primary>pmGetInDomArchive function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(1)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmLookupDesc<indexterm id="IG31340177334"><primary>pmLookupDesc function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(3)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmLookupInDom<indexterm id="IG31340177335"><primary>pmLookupInDom function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>(2)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmLookupInDomArchive<indexterm id="IG31340177336"><primary>pmLookupInDomArchive function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(1,2)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmLookupInDomText<indexterm id="IG31340177337"><primary>pmLookupInDomText function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(4)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmLookupName<indexterm id="IG31340177338"><primary>pmLookupName function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmLookupText<indexterm id="IG31340177339"><primary>pmLookupText function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(4)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmNameAll</command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmNameID<indexterm id="IG31340177340"><primary>pmNameID function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmNameInDom<indexterm id="IG31340177341"><primary>pmNameInDom function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para>(2)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmNameInDomArchive<indexterm id="IG31340177342"><primary>pmNameInDomArchive function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(1,2)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmSetMode<indexterm id="IG31340177343"><primary>pmSetMode function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmStore<indexterm id="IG31340177344"><primary>pmStore function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para>(5)</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTraversePMNS<indexterm id="IG31340177345"><primary>pmTraversePMNS function</primary></indexterm></command></para></entry> +<entry align="left" valign="top"><para>Yes</para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry> +<entry align="left" valign="top"><para> </para></entry></row></tbody></tgroup></table> +<para>Notes:</para> +<orderedlist><listitem><para>Operation supported only for PMAPI contexts where the source of metrics is an archive.</para> +</listitem><listitem><para><indexterm id="IG31340177346"><primary>specific instance domain</primary></indexterm>A specific instance domain is included in the arguments to these functions, and the result is independent of the instance profile for any PMAPI context.</para> +</listitem><listitem><para>The metadata that describes a performance metric is sensitive to the source of the metrics, but independent of any instance profile and of the collection time.</para> +</listitem><listitem><para><indexterm id="IG31340177347"><primary>archive logs</primary><secondary>context services</secondary></indexterm>Operation is supported only for PMAPI contexts where the source of metrics is a host. The text associated with a metric is assumed to be invariant with time and is definitely insensitive to the current members of the instance domain. In all cases this information is unavailable from an archive context (it is not included in the archive logs), and is directly available from a PMDA via PMCD in the other cases.</para> +</listitem><listitem><para>This operation is supported only for contexts where the source of the metrics is a host. Further, the instance identifiers are included in the argument to the function, and the effects upon the current values of the metrics are immediate (retrospective changes are not allowed). Consequently, from the current PMAPI context, neither the instance profile nor the collection time influence the result of this function.</para> +</listitem></orderedlist> +<section id="id5203779"> + +<title><command>pmNewContext</command> Function</title> +<programlisting>int pmNewContext(int <replaceable>type</replaceable>, const char *<replaceable>name</replaceable>)</programlisting> +<para><indexterm id="IG31340177348"><primary>PM_CONTEXT_ARCHIVE type</primary></indexterm><indexterm id="IG31340177349"><primary>PM_CONTEXT_HOST type</primary></indexterm><indexterm id="IG31340177350"><primary>pmNewContext function</primary></indexterm>The <command>pmNewContext</command> function may be used to establish a new PMAPI context. The source of metrics is identified by <replaceable>name</replaceable>, and may be a host specification (<replaceable>type</replaceable> is <literal>PM_CONTEXT_HOST</literal>) or the basename of an archive log (<replaceable>type</replaceable> is <literal>PM_CONTEXT_ARCHIVE</literal>).</para> +<para>A host specification usually contains a simple hostname, an internet address (IPv4 or IPv6), or the path to the PMCD Unix domain socket. It can also specify properties of the connection to PMCD, such as the protocol to use (secure and encrypted, or native) and whether PMCD should be reached via a <command>pmproxy</command> host. Various other connection attributes, such as authentication information (user name, password, authentication method, and so on) can also be specified. Further details can be found in the <command>PCPIntro(3)</command> man page, and the companion <citetitle>Performance Co-Pilot Tutorials and Case Studies</citetitle> document.</para> +<para>In the case where <replaceable>type</replaceable> is <literal>PM_CONTEXT_LOCAL</literal>, <replaceable>name</replaceable> is ignored, and the context uses a stand-alone connection to the PMDA methods used by PMCD. When this type of context is in effect, the range of accessible performance metrics is constrained to DSO PMDAs listed in the <command>pmcd</command> configuration file <filename>${PCP_PMCDCONF_PATH}</filename>. The reason this is done, as opposed to all of the DSO PMDAs found below <filename>${PCP_PMDAS_DIR}</filename> for example, is that DSO PMDAs listed there are very likely to have their metric names reflected in the local Name Space file, which will be loaded for this class of context.</para> +<para><indexterm id="IG31340177351"><primary>pmFetch function</primary></indexterm><indexterm id="IG31340177352"><primary>collection time</primary></indexterm>The initial instance profile is set up to select all instances in all instance domains, and the initial collection time is the current time at the time of each request for a host, or the time at the start of the log for an archive. In the case of archives, the initial collection time results in the earliest set of metrics being returned from the archive at the first <command>pmFetch</command>.</para> +<para>Once established, the association between a PMAPI context and a source of metrics is fixed for the life of the context; however, functions are provided to independently manipulate both the instance profile and the collection time components of a context.</para> +<para><indexterm id="IG31340177353"><primary>pmUseContext function</primary></indexterm>The function returns a “handle” that may be used in subsequent calls to <command>pmUseContext</command>. This new PMAPI context stays in effect for all subsequent context sensitive calls across the PMAPI until another call to <command>pmNewContext</command> is made, or the context is explicitly changed with a call to <command>pmDupContext</command> or <command>pmUseContext</command>.</para> +<para>For the python bindings creating and destroying a PMAPI context is done by creating and destroying an object of the pmapi class.</para> +</section> +<section id="id5203964"> + +<title><command>pmDestroyContext</command> Function</title> +<programlisting>int pmDestroyContext(int <replaceable>handle</replaceable>)</programlisting> +<para><indexterm id="IG31340177354"><primary>pmDestroyContext function</primary></indexterm>The PMAPI context identified by <replaceable>handle</replaceable> is destroyed. Typically, this implies terminating a connection to PMCD or closing an archive file, and orderly clean-up. The PMAPI context must have been previously created using <command>pmNewContext</command> or <command>pmDupContext</command>.</para> +<para>On success, <command>pmDestroyContext</command> returns zero. If <replaceable>handle</replaceable> was the current PMAPI context, then the current context becomes undefined. This means the application must explicitly re-establish a valid PMAPI context with <command>pmUseContext</command>, or create a new context with <command>pmNewContext</command> or <command>pmDupContext</command>, before the next PMAPI operation requiring a PMAPI context.</para> +<para>For the python bindings creating and destroying a PMAPI context is done by creating and destroying an object of the pmapi class.</para> + +</section> +<section id="id5204063"> + +<title><command>pmDupContext</command> Function</title> +<programlisting>int pmDupContext(void)</programlisting> +<programlisting></programlisting> +<para><indexterm id="IG31340177355"><primary>pmDupContext function</primary></indexterm>Replicate the current PMAPI context (source, instance profile, and collection time). This function returns a handle for the new context, which may be used with subsequent calls to <command>pmUseContext</command>. The newly replicated PMAPI context becomes the current context.</para> +</section> +<section id="id5204116"> + +<title><command>pmUseContext</command> Function</title> +<programlisting>int pmUseContext(int <replaceable>handle</replaceable>)</programlisting> +<para><indexterm id="IG31340177356"><primary>pmUseContext function</primary></indexterm>Calling <command>pmUseContext</command> causes the current PMAPI context to be set to the context identified by <replaceable>handle</replaceable>. The value of <replaceable>handle</replaceable> must be one returned from an earlier call to <command>pmNewContext</command> or <command>pmDupContext</command>.</para> +<para>Below the PMAPI, all contexts used by an application are saved in their most recently modified state, so <command>pmUseContext</command> restores the context to the state it was in the last time the context was used, not the state of the context when it was established.</para> +</section> +<section id="id5204177"> + +<title><command>pmWhichContext</command> Function</title> +<programlisting>int pmWhichContext(void) +<command>Python:</command> +int <replaceable>ctx</replaceable>_idx = pmWhichContext()</programlisting> +<para><indexterm id="IG31340177357"><primary>collection time</primary></indexterm><indexterm id="IG31340177358"><primary>pmWhichContext function</primary></indexterm>Returns the handle for the current PMAPI context (source, instance profile, and collection time).</para> +<para> +The python bindings return the handle of the current PMAPI context. +</para> +</section> +<section id="id5204210"> + +<title><command>pmAddProfile</command> Function</title> +<programlisting>int pmAddProfile(pmInDom <replaceable>indom</replaceable>, int <replaceable>numinst</replaceable>, int <replaceable>instlist</replaceable>[]) +<command>Python:</command> +int <replaceable>status</replaceable> = pmAddProfile(pmDesc pmdesc, [c_uint instid])</programlisting> +<para><indexterm id="IG31340177359"><primary>indom instance domain</primary></indexterm><indexterm id="IG31340177360"><primary>instlist argument</primary></indexterm><indexterm id="IG31340177361"><primary>pmAddProfile function</primary></indexterm>Add new instance specifications to the instance profile of the current PMAPI context. At its simplest, instances identified by the <replaceable>instlist</replaceable> argument for the <replaceable>indom</replaceable> instance domain are added to the instance profile. The list of instance identifiers contains <replaceable>numinst</replaceable> values.</para> +<para><indexterm id="IG31340177362"><primary>PM_INDOM_NULL instance domain</primary><secondary>pmAddProfile function</secondary></indexterm>If <replaceable>indom</replaceable> equals <literal>PM_INDOM_NULL</literal>, or <replaceable>numinst</replaceable> is zero, then all instance domains are selected. If <replaceable>instlist</replaceable> is NULL, then all instances are selected. To enable all available instances in all domains, use this syntax:</para> +<programlisting>pmAddProfile(PM_INDOM_NULL, 0, NULL).</programlisting> +<para> +The python bindings add the list of instances <replaceable>instid</replaceable> to the instance profile of the instance <replaceable>pmdesc</replaceable>. +</para> +</section> +<section id="id5204360"> + +<title><command>pmDelProfile</command> Function</title> +<programlisting>int pmDelProfile(pmInDom <replaceable>indom</replaceable>, int <replaceable>numinst</replaceable>, int <replaceable>instlist</replaceable>[]) +<command>Python:</command> +int <replaceable>status</replaceable> = pmDelProfile(pmDesc pmdesc, c_uint instid) +int <replaceable>status</replaceable> = pmDelProfile(pmDesc pmdesc, [c_uint instid]) +</programlisting> +<para><indexterm id="IG31340177363"><primary>PM_INDOM_NULL instance domain</primary><secondary>pmDelProfile function</secondary></indexterm><indexterm id="IG31340177364"><primary>pmDelProfile function</primary></indexterm>Delete instance specifications from the instance profile of the current PMAPI context. In the simplest variant, the list of instances identified by the <replaceable>instlist</replaceable> argument for the <replaceable>indom</replaceable> instance domain is removed from the instance profile. The list of instance identifiers contains <replaceable>numinst</replaceable> values.</para> +<para>If <replaceable>indom</replaceable> equals <literal>PM_INDOM_NULL</literal>, then all instance domains are selected for deletion. If <replaceable>instlist</replaceable> is NULL, then all instances in the selected domains are removed from the profile. To disable all available instances in all domains, use this syntax:</para> +<programlisting>pmDelProfile(PM_INDOM_NULL, 0, NULL) </programlisting> +<para> +The python bindings delete the list of instances <replaceable>instid</replaceable> from the instance profile of the instance domain <replaceable>pmdesc</replaceable>. +</para> +</section> +<section id="id5204444"> + +<title><command>pmSetMode</command> Function</title> +<programlisting>int pmSetMode(int <replaceable>mode</replaceable>, const struct timeval *<replaceable>when</replaceable>, int <replaceable>delta</replaceable>) +<command>Python:</command> +int <replaceable>status</replaceable> = pmSetMode(mode, timeVal <replaceable>timeval</replaceable>, int <replaceable>delta</replaceable>)</programlisting> +<para><indexterm id="IG31340177365"><primary>pmNameInDom function</primary></indexterm><indexterm id="IG31340177366"><primary>pmLookupInDom function</primary></indexterm><indexterm id="IG31340177367"><primary>pmGetInDom function</primary></indexterm><indexterm id="IG31340177368"><primary>pmLookupDesc function</primary></indexterm><indexterm id="IG31340177369"><primary>pmFetchArchive function</primary></indexterm><indexterm id="IG31340177370"><primary>pmFetch function</primary></indexterm><indexterm id="IG31340177371"><primary>pmSetMode function</primary></indexterm>This function defines the collection time and mode for accessing performance metrics and metadata in the current PMAPI context. This mode affects the semantics of subsequent calls to the following PMAPI functions: <command>pmFetch</command>, <command>pmFetchArchive</command>, <command>pmLookupDesc</command>, <command>pmGetInDom</command>, <command>pmLookupInDom +</command>, and <command>pmNameInDom</command>.</para> +<para>The <command>pmSetMode</command> function requires the current PMAPI context to be of type <literal>PM_CONTEXT_ARCHIVE</literal>.</para> +<para>The <replaceable>when</replaceable> parameter defines a time origin, and all requests for metadata (metrics descriptions and instance identifiers from the instance domains) are processed to reflect the state of the metadata as of the time origin. For example, use the last state of this information at, or before, the time origin.</para> +<para>If the <replaceable>mode</replaceable> is <literal>PM_MODE_INTERP</literal> then, in the case of <command>pmFetch</command>, the underlying code uses an interpolation scheme to compute the values of the metrics from the values recorded for times in the proximity of the time origin.</para> +<para>If the <replaceable>mode</replaceable> is <literal>PM_MODE_FORW</literal>, then, in the case of <command>pmFetch</command>, the collection of recorded metric values is scanned forward, until values for at least one of the requested metrics is located after the time origin. Then all requested metrics stored in the PCP archive at that time are returned with a corresponding time stamp. This is the default mode when an archive context is first established with <command>pmNewContext</command>.</para> +<para>If the <replaceable>mode</replaceable> is <literal>PM_MODE_BACK</literal>, then the situation is the same as for <literal>PM_MODE_FORW</literal>, except a <command>pmFetch</command> is serviced by scanning the collection of recorded metrics backward for metrics before the time origin.</para> +<para>After each successful <command>pmFetch</command>, the time origin is reset to the time stamp returned through the <filename>pmResult</filename>.</para> +<para>The <command>pmSetMode</command> parameter <replaceable>delta</replaceable> defines an additional number of time unit that should be used to adjust the time origin (forward or backward) after the new time origin from the <filename>pmResult</filename> has been determined. This is useful when moving through archives with a mode of <literal>PM_MODE_INTERP</literal>. The high-order bits of the <replaceable>mode</replaceable> parameter field is also used to optionally set the units of time for the <filename>delta</filename> field. To specify the units of time, use the <literal>PM_XTB_SET</literal> macro with one of the values <literal>PM_TIME_NSEC</literal>, <literal>PM_TIME_MSEC</literal>, <literal>PM_TIME_SEC</literal>, or so on as follows:</para> +<literallayout class="monospaced">PM_MODE_INTERP | PM_XTB_SET(PM_TIME_<replaceable>XXXX)</replaceable></literallayout> +<para>If no units are specified, the default is to interpret <replaceable>delta</replaceable> as milliseconds.</para> +<para>Using these mode options, an application can implement replay, playback, fast forward, or reverse for performance metric values held in a PCP archive log by alternating calls to <command>pmSetMode</command> and <command>pmFetch</command>.</para> +<para>In <xref linkend="Z976827209sdc"/>, the code fragment may be used to dump only those values stored in correct temporal sequence, for the specified performance metric <filename>my.metric.name</filename>:</para> +<example id="Z976827209sdc"> +<title>Dumping Values in Temporal Sequence</title> +<programlisting> int sts; + pmID pmid; + char *name = “my.metric.name”; + + sts = pmNewContext(PM_CONTEXT_ARCHIVE, “myarchive”); + sts = pmLookupName(1, &name, &pmid); + for ( ; ; ) { + sts = pmFetch(1, &pmid, &result); + if (sts < 0) + break; + /* dump value(s) from result->vset[0]->vlist[] */ + pmFreeResult(result); + }</programlisting> +</example> +<para><indexterm id="IG31340177372"><primary>interpolated metrics</primary></indexterm>Alternatively, the code fragment in <xref linkend="Z976827219sdc"/> may be used to replay interpolated metrics from an archive in reverse chronological order, at ten-second intervals (of recorded time):</para> +<example id="Z976827219sdc"> +<title>Replaying Interpolated Metrics</title> +<programlisting> int sts; + pmID pmid; + char *name = “my.metric.name”; + struct timeval endtime; + + sts = pmNewContext(PM_CONTEXT_ARCHIVE, “myarchive”); + sts = pmLookupName(1, &name, &pmid); + sts = pmGetArchiveEnd(&endtime); + sts = pmSetMode(PM_MODE_INTERP, &endtime, -10000); + while (pmFetch(1, &pmid, &result) != PM_ERR_EOL) { + /* + * process interpolated metric values as of result->timestamp + */ + pmFreeResult(result); + }</programlisting> +</example> +<para> +The python bindings define the collection +<replaceable>time</replaceable> and <replaceable>mode</replaceable> +for reading archive files. <replaceable>mode</replaceable> can be one +of: c_api.PM_MODE_LIVE, c_api.PM_MODE_INTERP, c_api.FORW, +c_api.BACK. wjocj are available by importing cpmapi. +</para> +</section> +<section id="id5204926"> + +<title><command>pmReconnectContext</command> Function</title> +<programlisting>int pmReconnectContext(int <replaceable>handle</replaceable>) +<command>Python:</command> +int <replaceable>status</replaceable> = pmReconnectContext() +</programlisting> +<para><indexterm id="IG31340177373"><primary>PMCD</primary><secondary>pmReconnectContext function</secondary></indexterm><indexterm id="IG31340177374"><primary>pmReconnectContext function</primary></indexterm>As a result of network, host, or PMCD (Performance Metrics Collection Daemon) failure, an application's connection to PMCD may be established and then lost.</para> +<para><indexterm id="IG31340177375"><primary>handle context</primary></indexterm>The function <command>pmReconnectContext</command> allows an application to request that the PMAPI context identified by <replaceable>handle</replaceable> be re-established, provided the associated PMCD is accessible.</para> +<note><para><replaceable>handle</replaceable> may or may not be the current context.</para> +</note> +<para><indexterm id="IG31340177376"><primary>PMCD_RECONNECT_TIMEOUT variable</primary></indexterm>To avoid flooding the system with reconnect requests, <command>pmReconnectContext</command> attempts a reconnection only after a suitable delay from the previous attempt. This imposed restriction on the reconnect re-try time interval uses a default exponential back-off so that the initial delay is 5 seconds after the first unsuccessful attempt, then 10 seconds, then 20 seconds, then 40 seconds, and then 80 seconds thereafter. The intervals between reconnection attempts may be modified using the environment variable <literal>PMCD_RECONNECT_TIMEOUT</literal> and the time to wait before an attempted connection is deemed to have failed is controlled by the <literal>PMCD_CONNECT_TIMEOUT</literal> environment variable; +see the <command>PCPIntro(1)</command> man page.</para> +<para>If the reconnection succeeds, <command>pmReconnectContext</command> returns <replaceable>handle</replaceable>. Note that even in the case of a successful reconnection, <command>pmReconnectContext</command> does not change the current PMAPI context.</para> +<para> +The python bindings reestablish the connection for the context. +</para> +</section> +<section id="id5205074"> + +<title><command>pmGetContextHostName</command> Function</title> +<programlisting>const char *pmGetContextHostName(int <replaceable>id</replaceable>) +char *pmGetContextHostName_r(int <replaceable>id</replaceable>, char *<replaceable>buf</replaceable>, int <replaceable>buflen</replaceable>) +<command>Python:</command> +"hostname" = pmGetContextHostName() +</programlisting> +<para>Given a valid PCP context identifier previously created with <command>pmNewContext</command> or <command>pmDupContext</command>, the <command>pmGetContextHostName</command> function provides a possibility to retrieve a host name associated with a context regardless of the context type.</para> +<para>This function will use the <literal>pmcd.hostname</literal> metric if it is available, and so is able to provide an accurate hostname in the presence of connection tunnelling and port forwarding.</para> +<para>If <replaceable>id</replaceable> is not a valid PCP context identifier, this function returns a zero length string and therefore never fails.</para> +<para>In the case of <command>pmGetContextHostName</command>, the string value is held in a single static buffer, so concurrent calls may not produce the desired results. The <command>pmGetContextHostName_r</command> function allows a buffer and length to be passed in, into which the message is stored; this variant uses no shared storage and can be used in a thread-safe manner.</para> +<para> +The python bindings query the current context hostname. +</para> +</section> +</section> +<section id="LE34685-PARENT"> + +<title>PMAPI Timezone Services</title> +<para>The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) timezone services.</para> +<section id="id5205140"> + +<title><command>pmNewContextZone</command> Function</title> +<literallayout class="monospaced">int pmNewContextZone(void) +<command>Python:</command> +pmNewContextZone() +</literallayout> +<para><indexterm id="IG31340177377"><primary>PMAPI</primary><secondary>timezone services</secondary></indexterm><indexterm id="IG31340177378"><primary>timezone services</primary></indexterm><indexterm id="IG31340177379"><primary>pmNewContextZone function</primary></indexterm>If the current PMAPI context is an archive, the <command>pmNewContextZone</command> function uses the timezone from the archive label record to set the current reporting timezone. The current reporting timezone affects the timezone used by <command>pmCtime</command> and <command>pmLocaltime</command>.</para> +<para>If the current PMAPI context corresponds to a host source of metrics, <command>pmNewContextZone</command> executes a <command>pmFetch</command> to retrieve the value for the metric <literal>pmcd.timezone</literal> and uses that to set the current reporting timezone.</para> +<para>In both cases, the function returns a value to identify the current reporting timezone that may be used in a subsequent call to <command>pmUseZone</command> to restore this reporting timezone.</para> +<para><literal>PM_ERR_NOCONTEXT</literal> indicates the current PMAPI context is not valid. A return value less than zero indicates a fatal error from a system call, most likely <command>malloc</command>.</para> +</section> +<section id="id5205286"> + +<title><command>pmNewZone</command> Function</title> +<literallayout class="monospaced">int pmNewZone(const char *<replaceable>tz</replaceable>) +<command>Python:</command> +int <replaceable>tz_handle</replaceable> = pmNewZone(int <replaceable>tz</replaceable>)</literallayout> +<para><indexterm id="IG31340177380"><primary>pmNewZone function</primary></indexterm>The <command>pmNewZone</command> function sets the current reporting timezone, and returns a value that may be used in a subsequent call to <command>pmUseZone</command> to restore this reporting timezone. The current reporting timezone affects the timezone used by <command>pmCtime</command> and <command>pmLocaltime</command>.</para> +<para>The <replaceable>tz</replaceable> argument defines a timezone string, in the format described for the <literal>TZ</literal> environment variable. See the <command>environ(7)</command> man page.</para> +<para>A return value less than zero indicates a fatal error from a system call, most likely <command>malloc</command>.</para> +<para> +The python bindings create a new zone handle and set reporting timezone for the timezone defined by <replaceable>tz</replaceable>. +</para> +</section> +<section id="id5205362"> + +<title><command>pmUseZone</command> Function</title> +<literallayout class="monospaced">int pmUseZone(const int <replaceable>tz_handle</replaceable>) +<command>Python:</command> +int <replaceable>status</replaceable> = pmUseZone(int <replaceable>tz_handle</replaceable>) +</literallayout> +<para><indexterm id="IG31340177381"><primary>pmUseZone function</primary></indexterm>In the <command>pmUseZone</command> function, <replaceable>tz_handle</replaceable> identifies a reporting timezone as previously established by a call to <command>pmNewZone</command> or <command>pmNewContextZone</command>, and this becomes the current reporting timezone. The current reporting timezone effects the timezone used by <command>pmCtime</command> and <command>pmLocaltime</command>).</para> +<para>A return value less than zero indicates the value of <replaceable>tz_handle</replaceable> is not legal.</para> +<para> +The python bindings set the current reporting timezone defined by timezone <replaceable>tz_handle</replaceable>. +</para> +</section> +<section id="id5205444"> + +<title><command>pmWhichZone</command> Function</title> +<literallayout class="monospaced">int pmWhichZone(char **<replaceable>tz</replaceable>) +<command>Python:</command> +"zone string" = pmWhichZone()</literallayout> +<para><indexterm id="IG31340177382"><primary>pmWhichZone function</primary></indexterm>The <command>pmWhichZone</command> function returns the handle of the current timezone, as previously established by a call to <command>pmNewZone</command> or <command>pmNewContextZone</command>. If the call is successful (that is, there exists a current reporting timezone), a non-negative integer is returned and <replaceable>tz</replaceable> is set to point to a static buffer containing the timezone string itself. The current reporting timezone effects the timezone used by <command>pmCtime</command> and <command>pmLocaltime</command>.</para> +<para>A return value less than zero indicates there is no current reporting timezone.</para> +<para> +The python bindings return the current reporting timezone. +</para> +</section> +</section> +<section id="LE25844-PARENT"> + +<title>PMAPI Metrics Services</title> +<para>The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) metrics services.</para> +<section id="Z1034802678tls"> + +<title><command>pmFetch</command> Function</title> +<programlisting>int pmFetch(int <replaceable>numpmid</replaceable>, pmID <replaceable>pmidlist</replaceable>[], pmResult **<replaceable>result</replaceable>) +<command>Python:</command> +pmResult* <replaceable>pmresult</replaceable> = pmFetch(c_uint <replaceable>pmid[]</replaceable>)</programlisting> +<para><indexterm id="IG31340177383"><primary>PMAPI </primary><secondary>metrics services</secondary></indexterm><indexterm id="IG31340177384"><primary>metrics services</primary></indexterm><indexterm id="IG31340177385"><primary>pmFetch function</primary></indexterm>The most common PMAPI operation is likely to be calls to <command>pmFetch</command>, specifying a list of PMIDs (for example, as constructed by <command>pmLookupName</command>) through <replaceable>pmidlist</replaceable> and <replaceable>numpmid</replaceable>. The call to <command>pmFetch</command> is executed in the context of a source of metrics, instance profile, and collection time, previously established by calls to the functions described in <xref linkend="LE94187-PARENT"/>.</para> +<para>The principal result from <command>pmFetch</command> is returned as a tree structured <replaceable>result</replaceable>, described in the <xref linkend="LE82331-PARENT"/>.</para> +<para>If one value (for example, associated with a particular instance) for a requested metric is unavailable at the requested time, then there is no associated <command>pmValue</command> structure in the result. If there are no available values for a metric, then <replaceable>numval</replaceable> is zero and the associated <command>pmValue</command>[] instance is empty; <replaceable>valfmt</replaceable> is undefined in these circumstances, but <replaceable>pmid</replaceable> is correctly set to the PMID of the metric with no values.</para> +<para>If the source of the performance metrics is able to provide a reason why no values are available for a particular metric, this reason is encoded as a standard error code in the corresponding <replaceable>numval</replaceable>; see the <command>pmerr(1)</command> and <command>pmErrStr(3)</command> man pages. Since all error codes are negative, values for a requested metric are unavailable if <replaceable>numval</replaceable> is less than or equal to zero.</para> +<para>The argument definition and the result specifications have been constructed to ensure that for each PMID in the requested <replaceable>pmidlist</replaceable> there is exactly one <command>pmValueSet</command> in the result, and that the PMIDs appear in exactly the same sequence in both <replaceable>pmidlist</replaceable> and <replaceable>result</replaceable>. This makes the number and order of entries in <replaceable>result</replaceable> completely deterministic, and greatly simplifies the application programming logic after the call to <command>pmFetch</command>.</para> +<para><indexterm id="IG31340177386"><primary>pmFreeResult function</primary></indexterm>The result structure returned by <command>pmFetch</command> is dynamically allocated using one or more calls to <command>malloc</command> and specialized allocation strategies, and should be released when no longer required by calling <command>pmFreeResult</command>. Under no circumstances should <command>free</command> be called directly to release this space.</para> +<para>As common error conditions are encoded in the result data structure, only serious events (such as loss of connection to PMCD, <command>malloc</command> failure, and so on) would cause an error value to be returned by <command><indexterm id="IG31340177387"><primary>pmFetch function</primary></indexterm>pmFetch</command>. Otherwise, the value returned by the <command>pmFetch</command> function is zero.</para> +<para>In <xref linkend="Z976559487sdc"/>, the code fragment dumps the values (assumed to be stored in the <replaceable>lval</replaceable> element of the <filename>pmValue</filename> structure) of selected performance metrics once every 10 seconds:</para> +<example id="Z976559487sdc"> +<title>PMAPI Metrics Services</title> +<programlisting> int i, j, sts; + pmID pmidlist[10]; + pmResult *result; + time_t now; + + /* set up PMAPI context, numpmid and pmidlist[] ... */ + while ((sts = pmFetch(10, pmidlist, &result)) >= 0) { + now = (time_t)result->timestamp.tv_sec; + printf("\n@ %s", ctime(&now)); + for (i = 0; i < result->numpmid; i++) { + printf("PMID: %s", pmIDStr(result->vset[i]->pmid)); + for (j = 0; j < result->vset[i]->numval; j++) { + printf(" 0x%x", result->vset[i]->vlist[j].value.lval); + putchar('\n'); + } + } + pmFreeResult(result); + sleep(10); + }</programlisting> +</example> +<note><para><indexterm id="IG31340177388"><primary>PM_ERR_TIMEOUT error code</primary></indexterm><indexterm id="IG31340177389"><primary>PMCD_REQUEST_TIMOUT variable</primary></indexterm>If a response is not received back from PMCD within 10 seconds, the <command>pmFetch</command> times out and returns <literal>PM_ERR_TIMEOUT</literal>. This is most likely to occur when the PMAPI client and PMCD are communicating over a slow network connection, but may also occur when one of the hosts is extremely busy. The time out period may be modified using the <literal>PMCD_REQUEST_TIMEOUT</literal> environment variable; see the <command>PCPIntro(1)</command> man page.</para> +</note> +<para> +The python bindings fetch a pmResult corresponding to a <replaceable>pmid</replaceable> list, which is returned from <command>pmLookupName</command>. The returned <replaceable>pmresult</replaceable> is passed to <command>pmExtractValue</command>. +</para> +</section> +<section id="id5205941"> + +<title><command>pmFreeResult</command> Function</title> +<programlisting>void pmFreeResult(pmResult *<replaceable>result</replaceable>) +<command>Python:</command> +pmFreeResult(pmResult* <replaceable>pmresult</replaceable>)</programlisting> +<para><indexterm id="IG31340177390"><primary>pmFetch function</primary></indexterm><indexterm id="IG31340177391"><primary>pmFreeResult function</primary></indexterm>Release the storage previously allocated for a result by <command>pmFetch</command>.</para> +<para> +THe python bindings free a <replaceable>pmresult</replaceable> previously allocated by <command>pmFetch</command>. +</para> +</section> +<section id="id5206030"> + +<title><command>pmStore</command> Function</title> +<programlisting>int pmStore(const pmResult *<replaceable>request</replaceable>) +<command>Python:</command> +pmResult* <replaceable>pmresult</replaceable> = pmStore(pmResult* <replaceable>pmresult</replaceable>)</programlisting> +<para><indexterm id="IG31340177392"><primary>pmStore function</primary></indexterm>In some special cases it may be helpful to modify the current values of performance metrics in one or more underlying domains, for example to reset a counter to zero, or to modify a <firstterm>metric</firstterm>, which is a control variable within a Performance Metric Domain.</para> +<para><indexterm id="IG31340177393"><primary>pmStore function</primary></indexterm>The <command>pmStore</command> function is a lightweight inverse of <command>pmFetch</command>. The caller must build the <filename>pmResult</filename> data structure (which could have been returned from an earlier <command>pmFetch</command> call) and then call <command>pmStore</command>. It is an error to pass a <replaceable>request</replaceable> to <command>pmStore</command> in which the <literal>numval</literal> field within any of the <command>pmValueSet</command> structure has a value less than one.</para> +<para>The current PMAPI context must be one with a host as the source of metrics, and the current value of the nominated metrics is changed. For example, <command>pmStore</command> cannot be used to make retrospective changes to information in a PCP archive log.</para> +</section> +</section> +<section id="LE40692-PARENT"> + +<title>PMAPI Record-Mode Services</title> +<para>The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) record-mode services. These services allow a monitor tool to establish connections to <command>pmlogger</command> co-processes, which they create and control for the purposes of recording live performance data from (possibly) multiple hosts. Since <command>pmlogger</command> records for one host only, these services can administer a group of loggers, and set up archive folios to track the logs. Tools like <command>pmafm</command> can subsequently use those folios to replay recorded data with the initiating tool. <command>pmchart</command> uses these concepts when providing its Record mode functionality.</para> +<section id="LE13213-PARENT"> + +<title><command>pmRecordAddHost</command> Function</title> +<literallayout class="monospaced">int pmRecordAddHost(const char *<replaceable>host</replaceable>, int <replaceable>isdefault</replaceable>, pmRecordHost **<replaceable>rhp</replaceable>) +<command>Python:</command> +(int <replaceable>status</replaceable>, pmRecordHost* <replaceable>rhp</replaceable>) = pmRecordAddHost("host string", 1, "configure string")</literallayout> +<para><indexterm id="IG31340177394"><primary>pmRecordAddHost function</primary></indexterm><indexterm id="IG31340177395"><primary>PMAPI</primary><secondary>record-mode services</secondary></indexterm><indexterm id="IG31340177396"><primary>record-mode services</primary></indexterm>The <command>pmRecordAddHost</command> function adds hosts once <command>pmRecordSetup</command> has established a new recording session. The <command>pmRecordAddHost</command> function along with the <command>pmRecordSetup</command> and <command>pmRecordControl</command> functions are used to create a PCP archive.</para> +<para><command>pmRecordAddHost</command> is called for each host that is to be included in the recording session. A new <filename>pmRecordHost</filename> structure is returned via <replaceable>rhp</replaceable>. It is assumed that PMCD is running on the host as this is how <command>pmlogger</command> retrieves the required performance metrics.</para> +<para>If this host is the default host for the recording session, <replaceable>isdefault</replaceable> is nonzero. This ensures that the corresponding archive appears first in the PCP archive <replaceable>folio</replaceable>. Hence the tools used to replay the archive <replaceable>folio</replaceable> make the correct determination of the archive associated with the default host. At most one host per recording session may be nominated as the default host.</para> +<para>The calling application writes the desired <command>pmlogger</command> configuration onto the stdio stream returned via the <literal>f_config</literal> field in the <filename>pmRecordHost</filename> structure.</para> +<para><command>pmRecordAddHost</command> returns 0 on success and a value less than 0 suitable for decoding with <command>pmErrStr</command> on failure. The value <literal>EINVAL</literal> has the same interpretation as <literal>errno</literal> being set to <literal>EINVAL</literal>.</para> +</section> +<section id="LE35969-PARENT"> + +<title><command>pmRecordControl</command> Function</title> +<literallayout class="monospaced">int pmRecordControl(pmRecordHost *<replaceable>rhp</replaceable>, int <replaceable>request</replaceable>, const char *<replaceable>options</replaceable>) +<command>Python:</command> +int <replaceable>status</replaceable> = pmRecordControl("host string", 1, "configure string")</literallayout> +<para><indexterm id="IG31340177397"><primary>pmRecordControl function</primary></indexterm>Arguments may be optionally added to the command line that is used to launch <command>pmlogger</command> by calling the <command>pmRecordControl</command> function with a request of <literal>PM_REC_SETARG</literal>. The <command>pmRecordControl</command> along with the <command>pmRecordSetup</command> and <command>pmRecordAddHost</command> functions are used to create a PCP archive.</para> +<para>The argument is passed via <replaceable>options</replaceable> and one call to <command>pmRecordControl</command> is required for each distinct argument. An argument may be added for a particular <command>pmlogger</command> instance identified by <replaceable>rhp</replaceable>. If the <replaceable>rhp</replaceable> argument is NULL, the argument is added for all <command>pmlogger</command> instances that are launched in the current recording session.</para> +<para>Independent of any calls to <command>pmRecordControl</command> with a request of <literal>PM_REC_SETARG</literal>, each <command>pmlogger</command> instance is automatically launched with the following arguments: <literal>-c</literal>, <literal>-h</literal>, <literal>-l</literal>, <literal>-x</literal>, and the basename for the PCP archive log.</para> +<para>To commence the recording session, call <command>pmRecordControl</command> with a request of <literal>PM_REC_ON</literal>, and <replaceable>rhp</replaceable> must be NULL. This launches one <command>pmlogger</command> process for each host in the recording session and initializes the <literal>fd_ipc</literal>, <literal>logfile</literal>, <literal>pid</literal>, and <literal>status</literal> fields in the associated <filename>pmRecordHost</filename> structure(s).</para> +<para>To terminate a <command>pmlogger</command> instance identified by <replaceable>rhp</replaceable>, call <command>pmRecordControl</command> with a request of <literal>PM_REC_OFF</literal>. If the <replaceable>rhp</replaceable> argument to <command>pmRecordControl</command> is NULL, the termination request is broadcast to all <command>pmlogger</command> processes in the current recording session. An informative dialogue is generated directly by each <command>pmlogger</command> process.</para> +<para>To display the current status of the <command>pmlogger</command> instance identified by <replaceable>rhp</replaceable>, call <command>pmRecordControl</command> with a request of <literal>PM_REC_STATUS</literal>. If the <replaceable>rhp</replaceable> argument to <command>pmRecordControl</command> is NULL, the status request is broadcast to all <command>pmlogger</command> processes in the current recording session. The display is generated directly by each <command>pmlogger</command> process.</para> +<para>To detach a <command>pmlogger</command> instance identified by <replaceable>rhp</replaceable>, allow it to continue independent of the application that launched the recording session and call <command>pmRecordControl</command> with a request of <literal>PM_REC_DETACH</literal>. If the <replaceable>rhp</replaceable> argument to <command>pmRecordControl</command> is NULL, the detach request is broadcast to all <command>pmlogger</command> processes in the current recording session.</para> +<para><command>pmRecordControl</command> returns 0 on success and a value less than 0 suitable for decoding with <command>pmErrStr</command> on failure. The value <literal>EINVAL</literal> has the same interpretation as <literal>errno</literal> being set to <literal>EINVAL</literal>.</para> +<para><command>pmRecordControl</command> returns <literal>PM_ERR_IPC</literal> if the associated <command>pmlogger</command> process has already exited.</para> +</section> +<section id="id5206798"> + +<title><command>pmRecordSetup</command> Function</title> +<literallayout class="monospaced">FILE *pmRecordSetup(const char *<replaceable>folio</replaceable>, const char *<replaceable>creator</replaceable>, int <replaceable>replay</replaceable>) +<command>Python:</command> +int <replaceable>status</replaceable> = pmRecordSetup("folio string", "creator string", int replay)</literallayout> +<para><indexterm id="IG31340177398"><primary>pmRecordSetup function</primary></indexterm>The <command>pmRecordSetup</command> function along with the <command>pmRecordAddHost</command> and <command>pmRecordControl</command> functions may be used to create a PCP archive on the fly to support record-mode services for PMAPI client applications.</para> +<para>Each record mode session involves one or more PCP archive logs; each is created using a dedicated <command>pmlogger</command> process, with an overall Archive Folio format as understood by the <command>pmafm</command> command, to name and collect all of the archive logs associated with a single recording session.</para> +<para>The <filename>pmRecordHost</filename> structure is used to maintain state information between the creator of the recording session and the associated <command>pmlogger</command> process(es). The structure, shown in <xref linkend="Z976560662sdc"/>, is defined as:</para> +<example id="Z976560662sdc"> +<title><filename>pmRecordHost</filename> Structure</title> +<programlisting>typedef struct { + FILE *f_config; /* caller writes pmlogger configuration here */ + int fd_ipc; /* IPC channel to pmlogger */ + char *logfile; /* full pathname for pmlogger error logfile */ + pid_t pid; /* process id for pmlogger */ + int status; /* exit status, -1 if unknown */ +} pmRecordHost;</programlisting> +</example> +<para>In <xref linkend="id5206969"/>, the functions are used in combination to create a recording session.</para> +<procedure id="id5206969"> +<title>Creating a Recording Session</title> +<step><para>Call <command>pmRecordSetup</command> to establish a new recording session. A new Archive Folio is created using the name <replaceable>folio</replaceable>. If the <replaceable>folio</replaceable> file or directory already exists, or if it cannot be created, this is an error. The application that is creating the session is identified by creator (most often this would be the same as the global PMAPI application name, <literal>pmProgname</literal>). If the application knows how to create its own configuration file to replay the recorded session, replay should be nonzero. The <command>pmRecordSetup</command> function returns a stdio stream onto which the application writes the text of any required replay configuration file.</para></step> +<step><para>For each host that is to be included in the recording session, call <command>pmRecordAddHost</command>. A new <filename>pmRecordHost</filename> structure is returned via <replaceable>rhp</replaceable>. It is assumed that PMCD is running on the host as this is how <command>pmlogger</command> retrieves the required performance metrics. See <xref linkend="LE13213-PARENT"/> for more information.</para></step> +<step><para>Optionally, add arguments to the command line that is used to launch <command>pmlogger</command> by calling <command>pmRecordControl</command> with a request of <literal>PM_REC_SETARG</literal>. The argument is passed via options and one call to <command>pmRecordControl</command> is required for each distinct argument. See <xref linkend="LE35969-PARENT"/> for more information.</para></step> +<step><para>To commence the recording session, call <command>pmRecordControl</command> with a request of <literal>PM_REC_ON</literal>, and <replaceable>rhp</replaceable> must be NULL.</para></step> +<step><para>To terminate a <command>pmlogger</command> instance identified by <replaceable>rhp</replaceable>, call <command>pmRecordControl</command> with a request of <literal>PM_REC_OFF</literal>.</para></step> +<step><para>To display the current status of the <command>pmlogger</command> instance identified by <replaceable>rhp</replaceable>, call <command>pmRecordControl</command> with a request of <literal>PM_REC_STATUS</literal>.</para></step> +<step><para>To detach a <command>pmlogger</command> instance identified by <replaceable>rhp</replaceable>, allow it to continue independent of the application that launched the recording session, call <command>pmRecordControl</command> with a request of <literal>PM_REC_DETACH</literal>.</para></step> +</procedure> +<para>The calling application should not close any of the returned stdio streams; <command>pmRecordControl</command> performs this task when recording is commenced.</para> +<para>Once <command>pmlogger</command> has been started for a recording session, <command>pmlogger</command> assumes responsibility for any dialogue with the user in the event that the application that launched the recording session should exit, particularly without terminating the recording session.</para> +<para>By default, information and dialogues from <command>pmlogger</command> is displayed using <command>pmconfirm</command>. This default is based on the assumption that most applications launching a recording session are GUI-based. In the event that <command>pmconfirm</command> fails to display the information (for example, because the <literal>DISPLAY</literal> environment variable is not set), <command>pmlogger</command> writes on its own stderr stream (not the stderr stream of the launching process). The output is assigned to the <filename><replaceable>xxxxxx</replaceable>.host.log</filename> file. For convenience, the full pathname to this file is provided via the <literal>logfile</literal> field in the <filename>pmRecordHost</filename> structure.</para> +<para>If the <replaceable>options</replaceable> argument to <command>pmRecordControl</command> is not NULL, this string may be used to pass additional arguments to <command>pmconfirm</command> in those cases where a dialogue is to be displayed. One use of this capability is to provide a -geometry string to control the placement of the dialogue.</para> +<para>Premature termination of a launched <command>pmlogger</command> process may be determined using the <filename>pmRecordHost</filename> structure, by calling <command>select</command> on the <literal>fd_ipc</literal> field or polling the <literal>status</literal> field that will contain the termination status from <command>waitpid</command> if known, or -1.</para> +<para>These functions create a number of files in the same directory as the <replaceable>folio</replaceable> file named in the call to <command>pmRecordSetup</command>. In all cases, the <replaceable>xxxxxx</replaceable> component is the result of calling <command>mkstemp</command>.</para> +<itemizedlist> +<listitem><para>If replay is nonzero, <replaceable>xxxxxx</replaceable> is the creator's replay configuration file, else an empty control file, used to guarantee uniqueness.</para> +</listitem> +<listitem><para>The <replaceable>folio</replaceable> file is the PCP Archive Folio, suitable for use with the <command>pmafm</command> command.</para> +</listitem> +<listitem><para>The <filename><replaceable>xxxxxx</replaceable>.host.confi</filename>g file is the <command>pmlogger</command> configuration for each host. If the same host is used in different calls to <command>pmRecordAddHost</command> within the same recording session, one of the letters 'a' through 'z' is appended to the <replaceable>xxxxxx</replaceable> part of all associated file names to ensure uniqueness.</para> +</listitem> +<listitem><para><filename><replaceable>xxxxxx</replaceable>.host.log</filename> is stdout and stderr for the <command>pmlogger</command> instance for each host.</para> +</listitem> +<listitem><para>The <filename><replaceable>xxxxxx</replaceable>.host.{0,meta,index}</filename> files comprise a single PCP archive for each host.</para> +</listitem></itemizedlist> +<para><command>pmRecordSetup</command> may return NULL in the event of an error. Check <literal>errno</literal> for the real cause. The value <literal>EINVAL</literal> typically means that the order of calls to these functions is not correct; that is, there is an obvious state associated with the current recording session that is maintained across calls to the functions.</para> +<para>For example, calling <command>pmRecordControl</command> before calling <command>pmRecordAddHost</command> at least once, or calling <command>pmRecordAddHost</command> before calling <command>pmRecordSetup</command> would produce an <literal>EINVAL</literal> error.</para> +</section> +</section> +<section id="LE85604-PARENT"> + +<title>PMAPI Archive-Specific Services</title> +<para>The functions described in this section provide archive-specific services.</para> +<section id="id5207510"> + +<title><command>pmGetArchiveLabel</command> Function</title> +<programlisting>int pmGetArchiveLabel(pmLogLabel *<replaceable>lp</replaceable>) +<command>Python:</command> +pmLogLabel <replaceable>loglabel</replaceable> = pmGetArchiveLabel()</programlisting> +<para><indexterm id="IG31340177399"><primary>pmGetArchiveLabel function</primary></indexterm><indexterm id="IG31340177400"><primary>PMAPI</primary><secondary>archive-specific services</secondary></indexterm><indexterm id="IG31340177401"><primary>archive-specific services</primary></indexterm>Provided the current PMAPI context is associated with a PCP archive log, the <command>pmGetArchiveLabel</command> function may be used to fetch the label record from the archive. The structure returned through <replaceable>lp</replaceable> is as shown in <xref linkend="Z976561683sdc"/>:</para> +<example id="Z976561683sdc"> +<title><filename>pmLogLabel</filename> Structure</title> +<programlisting>/* + * Label Record at the start of every log file - as exported above the PMAPI ... + */ +#define PM_TZ_MAXLEN 40 +#define PM_LOG_MAXHOSTLEN 64 +#define PM_LOG_MAGIC 0x50052600 +#define PM_LOG_VERS01 0x1 +#define PM_LOG_VERS02 0x2 +#define PM_LOG_VOL_TI -2 /* temporal index */ +#define PM_LOG_VOL_META -1 /* meta data */ +typedef struct { + int ll_magic; /* PM_LOG_MAGIC | log format version no. */ + pid_t ll_pid; /* PID of logger */ + struct timeval ll_start; /* start of this log */ + char ll_hostname[PM_LOG_MAXHOSTLEN]; /* name of collection host */ + char ll_tz[PM_TZ_MAXLEN]; /* $TZ at collection host */ +} pmLogLabel;</programlisting> +</example> +<para> +The python bindings get the label record from the archive. +</para> +</section> +<section id="id5207673"> + +<title><command>pmGetArchiveEnd</command> Function</title> +<programlisting>int pmGetArchiveEnd(struct timeval *<replaceable>tvp</replaceable>) +<command>Python:</command> +timeval <replaceable>tv</replaceable> = <replaceable>status</replaceable> = pmGetArchiveEnd()</programlisting> +<para><indexterm id="IG31340177402"><primary>archive logs</primary><secondary>pmGetArchiveEnd function</secondary></indexterm><indexterm id="IG31340177403"><primary>pmGetArchiveEnd function</primary></indexterm><indexterm id="IG31340177404"><primary>pmSetMode function</primary></indexterm>Provided the current PMAPI context is associated with a PCP archive log, <command>pmGetArchiveEnd</command> finds the logical end of file (after the last complete record in the archive), and returns the last recorded time stamp with <replaceable>tvp</replaceable>. This timestamp may be passed to <command>pmSetMode</command> to reliably position the context at the last valid log record, for example, in preparation for subsequent reading in reverse chronological order.</para> +<para>For archive logs that are not concurrently being written, the physical end of file and the logical end of file are co-incident. However, if an archive log is being written by <command>pmlogger</command> at the same time that an application is trying to read the archive, the logical end of file may be before the physical end of file due to write buffering that is not aligned with the logical record boundaries.</para> +<para> + The python bindings get the last recorded timestamp from the archive. +</para> +</section> +<section id="id5207751"> + +<title><command>pmGetInDomArchive</command> Function</title> +<programlisting>int pmGetInDomArchive(pmInDom <replaceable>indom</replaceable>, int **<replaceable>instlist</replaceable>, char ***<replaceable>namelist</replaceable> ) +<command>Python:</command> +((instance1, instance2...) (name1, name2...)) pmGetInDom(pmDesc <replaceable>pmdesc</replaceable>)</programlisting> +<para><indexterm id="IG31340177405"><primary>archive logs</primary><secondary>pmGetInDomArchive function</secondary></indexterm><indexterm id="IG31340177406"><primary>indom instance domain</primary></indexterm><indexterm id="IG31340177407"><primary>pmGetInDomArchive function</primary></indexterm>Provided the current PMAPI context is associated with a PCP archive log, <command>pmGetInDomArchive</command> scans the metadata to generate the union of all instances for the instance domain <replaceable>indom</replaceable> that can be found in the archive log, and returns through <replaceable>instlist</replaceable> the internal instance identifiers, and through <replaceable>namelist</replaceable> the full external identifiers.</para> +<para><indexterm id="IG31340177408"><primary>pmGetInDom function</primary></indexterm>This function is a specialized version of the more general PMAPI function <command>pmGetInDom</command>.</para> +<para>The function returns the number of instances found (a value less than zero indicates an error).</para> +<para>The resulting lists of instance identifiers (<replaceable>instlist</replaceable> and <replaceable>namelist</replaceable>), and the names that the elements of <replaceable>namelist</replaceable> point to, are allocated by <command>pmGetInDomArchive</command> with two calls to <command>malloc</command>, and it is the responsibility of the caller to use <command>free</command><replaceable>(instlist)</replaceable> and <command>free</command><replaceable>(namelist)</replaceable> to release the space when it is no longer required; see the <command>malloc(3)</command> and <command>free(3)</command> man pages.</para> +<para>When the result of <command>pmGetInDomArchive</command> is less than one, both <replaceable>instlist</replaceable> and <replaceable>namelist</replaceable> are undefined (no space is allocated; so calling <command>free</command> is a singularly bad idea).</para> +<para> + The python bindings return a tuple of the instance IDs and names for the union of all instances for the instance domain <replaceable>pmdesc</replaceable> that can be found in the archive log. +</para> +</section> +<section id="id5207937"> + +<title><command>pmLookupInDomArchive</command> Function</title> +<literallayout class="monospaced">int pmLookupInDomArchive(pmInDom <replaceable>indom</replaceable>, const char *<replaceable>name</replaceable>) +<command>Python:</command> +c_uint <replaceable>instid</replaceable> = pmLookupInDomArchive(pmDesc <replaceable>pmdesc</replaceable>, "Instance")</literallayout> +<para><indexterm id="IG31340177409"><primary>pmLookupInDomArchive function</primary></indexterm>Provided the current PMAPI context is associated with a PCP archive log, <command>pmLookupInDomArchive</command> scans the metadata for the instance domain <replaceable>indom</replaceable>, locates the first instance with the external identification given by <replaceable>name</replaceable>, and returns the internal instance identifier.</para> +<para>This function is a specialized version of the more general PMAPI function <command>pmLookupInDom</command>.</para> +<para>The <command>pmLookupInDomArchive</command> function returns a positive instance identifier on success.</para> +<para> + The python bindings return the instance id in <replaceable>pmdesc</replaceable> corresponding to <replaceable>Instance</replaceable>. +</para> +</section> +<section id="id5208032"> + +<title><command>pmNameInDomArchive</command> Function</title> +<literallayout class="monospaced">int pmNameInDomArchive(pmInDom <replaceable>indom</replaceable>, int <replaceable>inst</replaceable>, char **<replaceable>name</replaceable>) +<command>Python:</command> +"instance id" = pmNameInDomArchive(pmDesc <replaceable>pmdesc</replaceable>, c_uint <replaceable>instid</replaceable>)</literallayout> +<para><indexterm id="IG31340177410"><primary>pmNameInDomArchive function</primary></indexterm>Provided the current PMAPI context is associated with a PCP archive log, <command>pmNameInDomArchive</command> scans the metadata for the instance domain <replaceable>indom</replaceable>, locates the first instance with the internal instance identifier given by <command>inst</command>, and returns the full external instance identification through <replaceable>name</replaceable>. This function is a specialized version of the more general PMAPI function <command>pmNameInDom</command>.</para> +<para>The space for the value of <replaceable>name</replaceable> is allocated in <command>pmNameInDomArchive</command> with <command>malloc</command>, and it is the responsibility of the caller to free the space when it is no longer required; see the <command>malloc(3)</command> and<command>free(3)</command> man pages.</para> +<para> + The python bindings return the text name of an instance corresponding to an instance domain <replaceable>pmdesc</replaceable> with instance identifier <replaceable>instid</replaceable>. +</para> +</section> +<section id="id5208144"> + +<title><command>pmFetchArchive</command> Function</title> +<literallayout class="monospaced">int pmFetchArchive(pmResult **<replaceable>result</replaceable>) +<command>Python:</command> +pmResult* <replaceable>pmresult</replaceable> = pmFetchArchive()</literallayout> +<para><indexterm id="IG31340177411"><primary>pmFetch function</primary></indexterm><indexterm id="IG31340177412"><primary>pmFetchArchive function</primary></indexterm>This is a variant of <command>pmFetch</command> that may be used only when the current PMAPI context is associated with a PCP archive log. The <replaceable>result</replaceable> is instantiated with all of the metrics (and instances) from the next archive record; consequently, there is no notion of a list of desired metrics, and the instance profile is ignored.</para> +<para>It is expected that <command>pmFetchArchive</command> would be used to create utilities that scan archive logs (for example, <command>pmdumplog</command> and <command>pmlogsummary</command>), and the more common access to the archives would be through the <command>pmFetch</command> interface.</para> +</section> +</section> +<section id="LE73955-PARENT"> + +<title>PMAPI Time Control Services</title> +<para><indexterm id="IG31340177413"><primary>PMAPI</primary><secondary>time control services</secondary></indexterm><indexterm id="IG31340177414"><primary>time control services</primary></indexterm>The PMAPI provides a common framework for client applications to control time and to synchronize time with other applications. The user interface component of this service is fully described in the companion <citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle>. See also the <command>pmtime(1)</command> man page.</para> +<para><indexterm id="IG31340177415"><primary>archive logs</primary><secondary>time control services</secondary></indexterm>This service is most useful when processing PCP archive logs, to control parameters such as the current archive position, update interval, replay rate, and timezone, but it can also be used in live mode to control a subset of these parameters. Applications such as <command>pmchart</command>, <command>pmgadgets</command>, <command>pmstat</command>, and <command>pmval</command> use the time control services to connect to an instance of the time control server process, <command>pmtime</command>, which provides a uniform graphical user interface to the time control services.</para> +<para><indexterm id="IG31340177416"><primary>examples</primary><secondary>time control functions </secondary></indexterm>A full description of the PMAPI time control functions along with code examples can be found in man pages as listed in <xref linkend="id5208351"/>:</para> +<table id="id5208351" frame="topbot" pgwide="wide"> + +<title>Time Control Functions in PMAPI</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="137*"/> +<colspec colwidth="259*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Man Page</para></entry><entry align="left" valign="bottom"><para>Synopsis of Time Control Function</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmCtime(3)</command></para></entry> +<entry align="left" valign="top"><para>Formats the date and time for a reporting timezone.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmLocaltime(3)</command></para></entry> +<entry align="left" valign="top"><para>Converts the date and time for a reporting timezone.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmParseTimeWindow(3)</command></para></entry> +<entry align="left" valign="top"><para>Parses time window command line arguments.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeConnect(3)</command></para></entry> +<entry align="left" valign="top"><para>Connects to a time control server via a command socket.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeDisconnect(3)</command></para></entry> +<entry align="left" valign="top"><para>Closes the command socket to the time control server.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeGetPort(3)</command></para></entry> +<entry align="left" valign="top"><para>Obtains the port name of the current time control server.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeRecv(3)</command></para></entry> +<entry align="left" valign="top"><para>Blocks until the time control server sends a command message.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeSendAck(3)</command></para></entry> +<entry align="left" valign="top"><para>Acknowledges completion of the step command.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeSendBounds(3)</command></para></entry> +<entry align="left" valign="top"><para>Specifies beginning and end of archive time period.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeSendMode(3)</command></para></entry> +<entry align="left" valign="top"><para>Requests time control server to change to a new VCR mode.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeSendPosition(3)</command></para></entry> +<entry align="left" valign="top"><para>Requests time control server to change position or update intervals.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeSendTimezone(3)</command></para></entry> +<entry align="left" valign="top"><para>Requests time control server to change timezones.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeShowDialog(3)</command></para></entry> +<entry align="left" valign="top"><para>Changes the visibility of the time control dialogue.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><command>pmTimeGetStatePixmap(3)</command></para></entry> +<entry align="left" valign="top"><para>Returns array of pixmaps representing supplied time control state.</para></entry></row></tbody></tgroup></table> +</section> +<section id="LE44064-PARENT"> + +<title>PMAPI Ancillary Support Services</title> +<para><indexterm id="IG31340177417"><primary>ancillary support services</primary></indexterm><indexterm id="IG31340177418"><primary>PMAPI</primary><secondary>ancillary support services</secondary></indexterm>The functions described in this section provide services that are complementary to, but not necessarily a part of, the distributed manipulation of performance metrics delivered by the PCP components.</para> +<section id="id5208965"> + +<title><command>pmGetConfig</command> Function</title> +<literallayout class="monospaced">char *pmGetConfig(const char <replaceable>*variable</replaceable>) +<command>Python:</command> +"env variable value = pmGetConfig("env variable")</literallayout> +<para>The <command>pmGetConfig</command> function searches for a variable first in the environment and then, if one is not found, in the PCP configuration file and returns the string result. If a variable is not already in the environment, it is added with a call to the <command>putenv</command> function before returning.</para> +<para>The default location of the PCP configuration file is <filename>/etc/pcp.conf</filename>, but this location may be changed by setting <literal>PCP_CONF</literal> in the environment to a new location, as described in the <command>pcp.conf(5)</command> man page.</para> +<para>If the variable is not found in either the environment or the PCP configuration file (or the PCP configuration file is not found and <literal>PCP_CONF</literal> is not set in the environment), then a fatal error message is printed and the process will exit. Although this sounds drastic, it is the only course of action available because the PCP configuration or installation is fatally flawed.</para> +<para>If this function returns, the returned value points to a string in the environment; and so although the function returns the same type as the <command>getenv</command> function (which should probably be a <literal>const char *</literal>), changing the content of the string is not recommended.</para> +<para> +The python bindings return a value for environment variable <replaceable>"env variable"</replaceable> from environment or pcp config file. +</para> +</section> +<section id="id5209050"> + +<title><command>pmErrStr</command> Function</title> +<literallayout class="monospaced">const char *pmErrStr(int <replaceable>code</replaceable>) +char *pmErrStr_r(int <replaceable>code</replaceable>, char *<replaceable>buf</replaceable>, int <replaceable>buflen</replaceable>); +<command>Python:</command> +"error string text" = pmErrStr(int <replaceable>error_code</replaceable>)</literallayout> +<para><indexterm id="IG31340177419"><primary>pmErrStr function</primary></indexterm>This function translates an error code into a text string, suitable for generating a diagnostic message. By convention within PCP, all error codes are negative. The small values are assumed to be negated versions of the platform error codes as defined in <filename>errno.h</filename>, and the strings returned are according to <command>strerror</command>. The large, negative error codes are PMAPI error conditions, and <command>pmErrStr</command> returns an appropriate PMAPI error string, as determined by <replaceable>code</replaceable>.</para> +<para>In the case of <command>pmErrStr</command>, the string value is held in a single static buffer, so concurrent calls may not produce the desired results. The <command>pmErrStr_r</command> function allows a buffer and length to be passed in, into which the message is stored; this variant uses no shared storage and can be used in a thread-safe manner.</para> +<para> +The python bindings return the error string corresponding to the <replaceable>error code</replaceable>. +</para> +</section> +<section id="id5209112"> + +<title><command>pmExtractValue</command> Function</title> +<literallayout class="monospaced">int pmExtractValue(int <replaceable>valfmt</replaceable>, const pmValue *<replaceable>ival</replaceable>, int <replaceable>itype</replaceable>, +pmAtomValue *<replaceable>oval</replaceable>, int <replaceable>otype</replaceable>) +<command>Python:</command> +pmAtomValue <replaceable>atomval</replaceable> = pmExtractValue(int <replaceable>valfmt</replaceable>, const pmValue * <replaceable>ival</replaceable>, + int <replaceable>itype</replaceable>, + pmAtomValue *<replaceable>oval</replaceable>, + int <replaceable>otype</replaceable>)</literallayout> +<para><indexterm id="IG31340177420"><primary>pmExtractValue function</primary></indexterm>The <command>pmValue</command> structure is embedded within the <filename>pmResult</filename> structure, which is used to return one or more performance metrics; see the <command>pmFetch</command> man page.</para> +<para>All performance metric values may be encoded in a <filename>pmAtomValue</filename> union, defined in <xref linkend="Z976562908sdc"/>:</para> +<example id="Z976562908sdc"> +<title><filename>pmAtomValue</filename> Structure</title> +<programlisting>/* Generic Union for Value-Type conversions */ +typedef union { + __int32_t l; /* 32-bit signed */ + __uint32_t ul; /* 32-bit unsigned */ + __int64_t ll; /* 64-bit signed */ + __uint64_t ull; /* 64-bit unsigned */ + float f; /* 32-bit floating point */ + double d; /* 64-bit floating point */ + char *cp; /* char ptr */ + void *vp; /* void ptr */ +} pmAtomValue;</programlisting> +</example> +<para>The <command>pmExtractValue</command> function provides a convenient mechanism for extracting values from the <command>pmValue</command> part of a <filename>pmResult</filename> structure, optionally converting the data type, and making the result available to the application programmer.</para> +<para><indexterm id="IG31340177421"><primary>pmLookupDesc function</primary></indexterm>The <replaceable>itype</replaceable> argument defines the data type of the input value held in <replaceable>ival</replaceable> according to the storage format defined by <replaceable>valfmt</replaceable> (see the <command>pmFetch</command> man page). The <replaceable>otype</replaceable> argument defines the data type of the result to be placed in <replaceable>oval</replaceable>. The value for <replaceable>itype</replaceable> is typically extracted from a <filename>pmDesc</filename> structure, following a call to <command>pmLookupDesc</command> for a particular performance metric.</para> +<para><xref linkend="id5209524"/> defines the various possibilities for the type conversion. The input type (<replaceable>itype</replaceable>) is shown vertically, and the output type (<replaceable>otype</replaceable>) horizontally. The following rules apply:</para> +<itemizedlist> +<listitem><para>Y means the conversion is always acceptable.</para> +</listitem> +<listitem><para><indexterm id="IG31340177422"><primary>PM_ERR_CONV error code</primary></indexterm>N means conversion can never be performed (function returns <literal>PM_ERR_CONV</literal>).</para> +</listitem> +<listitem><para>P means the conversion may lose accuracy (but no error status is returned).</para> +</listitem> +<listitem><para><indexterm id="IG31340177423"><primary>PM_ERR_TRUNC error code</primary></indexterm>T means the result may be subject to high-order truncation (if this occurs the function returns <literal>PM_ERR_TRUNC</literal>).</para> +</listitem> +<listitem><para><indexterm id="IG31340177424"><primary>PM_ERR_SIGN error code</primary></indexterm>S means the conversion may be impossible due to the sign of the input value (if this occurs the function returns <literal>PM_ERR_SIGN</literal>).</para> +</listitem></itemizedlist> +<para><indexterm id="IG31340177425"><primary>PM_TYPE_STRING type</primary></indexterm>If an error occurs, <replaceable>oval</replaceable> is set to zero (or NULL).</para> +<para><note><para> Note that some of the conversions involving the <literal>PM_TYPE_STRING</literal> and <literal>PM_TYPE_AGGREGATE</literal> types are indeed possible, but are marked N; the rationale is that <command>pmExtractValue</command> should not attempt to duplicate functionality already available in the C library through <command>sscanf</command> and <command>sprintf</command>. No conversion involving the type <literal>PM_TYPE_EVENT</literal> is supported.</para> +</note></para> +<table id="id5209524" frame="topbot"> + +<title>PMAPI Type Conversion</title> +<tgroup cols="10" colsep="0" rowsep="0"> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>TYPE</para></entry><entry align="left" valign="bottom"><para>32</para></entry><entry align="left" valign="bottom"><para>U32</para></entry><entry align="left" valign="bottom"><para>64</para></entry><entry align="left" valign="bottom"><para>U64</para></entry><entry align="left" valign="bottom"><para>FLOAT</para></entry><entry align="left" valign="bottom"><para>DBLE</para></entry><entry align="left" valign="bottom"><para>STRING</para></entry><entry align="left" valign="bottom"><para>AGGR</para></entry><entry align="left" valign="bottom"><para>EVENT</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><literal>32</literal></para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>S</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>S</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>U32</literal></para></entry> +<entry align="left" valign="top"><para>T</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>64</literal></para></entry> +<entry align="left" valign="top"><para>T</para></entry> +<entry align="left" valign="top"><para>T,S</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>S</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>u64</literal></para></entry> +<entry align="left" valign="top"><para>T</para></entry> +<entry align="left" valign="top"><para>T</para></entry> +<entry align="left" valign="top"><para>T</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>FLOAT</literal></para></entry> +<entry align="left" valign="top"><para>P, T</para></entry> +<entry align="left" valign="top"><para>P, T, S</para></entry> +<entry align="left" valign="top"><para>P, T</para></entry> +<entry align="left" valign="top"><para>P, T, S</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>DBLE</literal></para></entry> +<entry align="left" valign="top"><para>P, T</para></entry> +<entry align="left" valign="top"><para>P, T, S</para></entry> +<entry align="left" valign="top"><para>P, T</para></entry> +<entry align="left" valign="top"><para>P, T, S</para></entry> +<entry align="left" valign="top"><para>P</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>STRING</literal></para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>AGGR</literal></para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>Y</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>EVENT</literal></para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry> +<entry align="left" valign="top"><para>N</para></entry></row></tbody></tgroup></table> +<para>In the cases where multiple conversion errors could occur, the first encountered error is returned, and the order of checking is not defined.</para> +<para>If the output conversion is to one of the pointer types, such as <replaceable>otype</replaceable> <literal>PM_TYPE_STRING</literal> or <literal>PM_TYPE_AGGREGATE</literal>, then the value buffer is allocated by <command>pmExtractValue</command> using <command>malloc</command>, and it is the caller's responsibility to free the space when it is no longer required; see the <command>malloc(3)</command> and <command>free(3)</command> man pages.</para> +<para>Although this function appears rather complex, it has been constructed to assist the development of performance tools that convert values, whose type is known only through the <literal>type</literal> field in a <command>pmDesc</command> structure, into a canonical type for local processing.</para> +<para> +The python bindings extract a value from a pmValue struct <replaceable>ival</replaceable> stored in format <replaceable>valfmt</replaceable> (see <command>pmFetch</command>), and convert its type from <replaceable>itype</replaceable> to <replaceable>otype</replaceable>. +</para> +</section> +<section id="id5210752"> + +<title><command>pmConvScale</command> Function</title> +<programlisting>int +pmConvScale(int <replaceable>type</replaceable>, const pmAtomValue *<replaceable>ival</replaceable>, const pmUnits *<replaceable>iunit</replaceable>, +pmAtomValue *<replaceable>oval</replaceable>, pmUnits *<replaceable>ounit</replaceable>) +<command>Python:</command> +pmAtomValue <replaceable>atomval</replaceable> = pmConvScale(int <replaceable>itype</replaceable>, pmAtomValue value, + pmDesc* pmdesc , int descidx, int otype)</programlisting> +<para><indexterm id="IG31340177426"><primary>pmConvScale function</primary></indexterm>Given a performance metric value pointed to by <replaceable>ival</replaceable>, multiply it by a scale factor and return the value in <replaceable>oval</replaceable>. The scaling takes place from the units defined by <replaceable>iunit</replaceable> into the units defined by <replaceable>ounit</replaceable>. Both input and output units must have the same dimensionality.</para> +<para><indexterm id="IG31340177427"><primary>pmLookupDesc function</primary></indexterm>The performance metric type for both input and output values is determined by <replaceable>type</replaceable>, the value for which is typically extracted from a <filename>pmDesc</filename> structure, following a call to <command>pmLookupDesc</command> for a particular performance metric.</para> +<para><indexterm id="IG31340177428"><primary>pmExtractValue function</primary></indexterm><command>pmConvScale</command> is most useful when values returned through <command>pmFetch</command> (and possibly extracted using <command>pmExtractValue</command>) need to be normalized into some canonical scale and units for the purposes of computation.</para> +<para> +The python bindings convert a <replaceable>value</replaceable> pointed to by <replaceable>pmdesc</replaceable> entry <replaceable>descidx</replaceable> to a different scale <replaceable>otype</replaceable>. +</para> +</section> +<section id="id5210895"> + +<title><command>pmUnitsStr</command> Function</title> +<literallayout class="monospaced">const char *pmUnitsStr(const pmUnits *<replaceable>pu</replaceable>) +char *pmUnitsStr_r(const pmUnits *<replaceable>pu</replaceable>, char *<replaceable>buf</replaceable>, int <replaceable>buflen</replaceable>) +<command>Python:</command> +"units string" = pmUnitsStr(pmUnits <replaceable>pmunits</replaceable>)</literallayout> +<para><indexterm id="IG31340177429"><primary>pmUnitsStr function</primary></indexterm>As an aid to labeling graphs and tables, or for error messages, <command>pmUnitsStr</command> takes a dimension and scale specification as per <replaceable>pu</replaceable>, and returns the corresponding text string.</para> +<para><replaceable>pu</replaceable> is typically from a <filename>pmDesc</filename> structure, for example, as returned by <command>pmLookupDesc</command>.</para> +<para>If <replaceable>*pu</replaceable> were <literal>{1, -2, 0, PM_SPACE_MBYTE, PM_TIME_MSEC, 0}</literal>, then the result string would be <literal>Mbyte/sec^2</literal>.</para> +<para>In the case of <command>pmUnitsStr</command>, the string value is held in a single static buffer; so concurrent calls may not produce the desired results. The <command>pmUnitsStr_r</command> function allows a buffer and length to be passed in, into which the units are stored; this variant uses no shared storage and can be used in a thread-safe manner.</para> +<para> +The python bindings translate a pmUnits struct <replaceable>pmunits</replaceable> to a readable string. +</para> +</section> +<section id="id5210994"> + +<title><command>pmIDStr</command> Function</title> +<literallayout class="monospaced">const char *pmIDStr(pmID <replaceable>pmid</replaceable>) +char *pmIDStr_r(pmID <replaceable>pmid</replaceable>, char *<replaceable>buf</replaceable>, int <replaceable>buflen</replaceable>) +<command>Python:</command> +"ID string" = pmIDStr(int <replaceable>pmID</replaceable>)</literallayout> +<para><indexterm id="IG31340177430"><primary>pmIDStr function</primary></indexterm>For use in error and diagnostic messages, return a human readable version of the specified PMID, with each of the internal <literal>domain</literal>, <literal>cluster</literal>, and <literal>item</literal> subfields appearing as decimal numbers, separated by periods.</para> +<para>In the case of <command>pmIDStr</command>, the string value is held in a single static buffer; so concurrent calls may not produce the desired results. The <command>pmIDStr_r</command> function allows a buffer and length to be passed in, into which the identifier is stored; this variant uses no shared storage and can be used in a thread-safe manner.</para> +<para> +The python bindings translate a pmID <replaceable>pmid</replaceable> to a readable string. +</para> +</section> +<section id="id5211046"> + +<title><command>pmInDomStr</command> Function</title> +<literallayout class="monospaced">const char *pmInDomStr(pmInDom <replaceable>indom</replaceable>) +char *pmInDomStr_r(pmInDom <replaceable>indom</replaceable>, char *<replaceable>buf</replaceable>, int <replaceable>buflen</replaceable>) +<command>Python:</command> +"indom" = pmGetInDom(pmDesc <replaceable>pmdesc</replaceable>)</literallayout> +<para><indexterm id="IG31340177431"><primary>pmInDomStr function</primary></indexterm>For use in error and diagnostic messages, return a human readable version of the specified instance domain identifier, with each of the internal <literal>domain</literal> and <literal>serial</literal> subfields appearing as decimal numbers, separated by periods.</para> +<para>In the case of <command>pmInDomStrr</command>, the string value is held in a single static buffer; so concurrent calls may not produce the desired results. The <command>pmInDomStr_r</command> function allows a buffer and length to be passed in, into which the identifier is stored; this variant uses no shared storage and can be used in a thread-safe manner.</para> +<para> +The python bindings translate an instance domain ID pointed to by a pmDesc <replaceable>pmdesc</replaceable> to a readable string. +</para> +</section> +<section id="id5211095"> + +<title><command>pmTypeStr</command> Function</title> +<literallayout class="monospaced">const char *pmTypeStr(int <replaceable>type</replaceable>) +char *pmTypeStr_r(int <replaceable>type</replaceable>, char *<replaceable>buf</replaceable>, int <replaceable>buflen</replaceable>) +<command>Python:</command> +"type" = pmTypeStr(int <replaceable>type</replaceable>)</literallayout> +<para><indexterm id="IG31340177432"><primary>pmTypeStr function</primary></indexterm>Given a performance metric type, produce a terse ASCII equivalent, appropriate for use in error and diagnostic messages.</para> +<para>Examples are “32” (for <literal>PM_TYPE_32</literal>), “U64” (for <literal>PM_TYPE_U64</literal>), “AGGREGATE” (for <literal>PM_TYPE_AGGREGATE</literal>), and so on.</para> +<para>In the case of <command>pmTypeStr</command>, the string value is held in a single static buffer; so concurrent calls may not produce the desired results. The <command>pmTypeStr_r</command> function allows a buffer and length to be passed in, into which the identifier is stored; this variant uses no shared storage and can be used in a thread-safe manner.</para> +<para> +The python bindings translate a performance metric type to a readable string. Constants are available for the types, e.g. c_api.PM_TYPE_FLOAT, by importing cpmapi. +</para> +</section> +<section id="id5211169"> + +<title><command>pmAtomStr</command> Function</title> +<literallayout class="monospaced">const char *pmAtomStr(const pmAtomValue *<replaceable>avp</replaceable>, int <replaceable>type</replaceable>) +char *pmAtomStr_r(const pmAtomValue *<replaceable>avp</replaceable>, int <replaceable>type</replaceable>char *<replaceable>buf</replaceable>, int <replaceable>buflen</replaceable>) +<command>Python:</command> +"value" = pmAtomStr(<replaceable>atom</replaceable>, <replaceable>type</replaceable>)</literallayout> +<para><indexterm id="IG31340177433"><primary>pmAtomStr function</primary></indexterm>Given the <command>pmAtomValue</command> identified by <replaceable>avp</replaceable>, and a performance metric <replaceable>type</replaceable>, generate the corresponding metric value as a string, suitable for diagnostic or report output.</para> +<para>In the case of <command>pmAtomStr</command>, the string value is held in a single static buffer; so concurrent calls may not produce the desired results. The <command>pmAtomStr_r</command> function allows a buffer and length to be passed in, into which the identifier is stored; this variant uses no shared storage and can be used in a thread-safe manner.</para> +<para> +The python bindings translate a pmAtomValue <replaceable>atom</replaceable> having performance metric <replaceable>type</replaceable> to a readable string. Constants are available for the types, e.g. c_api.PM_TYPE_U32, by importing cpmapi. +</para> +</section> +<section id="id5211303"> + +<title><command>pmNumberStr</command> Function</title> +<literallayout class="monospaced">const char *pmNumberStr(double <replaceable>value</replaceable>) +char *pmNumberStr_r(double <replaceable>value</replaceable>, char *<replaceable>buf</replaceable>, int <replaceable>buflen</replaceable>)</literallayout> +<para><indexterm id="IG31340177434"><primary>pmNumberStr function</primary></indexterm>The <command>pmNumberStr</command> function returns the address of a static 8-byte buffer that holds a null-byte terminated representation of value suitable for output with fixed-width fields.</para> +<para>The value is scaled using multipliers in powers of one thousand (the decimal kilo) and has a bias that provides greater precision for positive numbers as opposed to negative numbers. The format depends on the sign and magnitude of <replaceable>value</replaceable>.</para> +</section> +<section id="id5211350"> + +<title><command>pmPrintValue</command> Function</title> +<literallayout class="monospaced">void pmPrintValue(FILE *<replaceable>f</replaceable>, int <replaceable>valfmt</replaceable>, int <replaceable>type</replaceable>, const pmValue *<replaceable>val</replaceable>, +int <replaceable>minwidth</replaceable>) +<command>Python:</command> +pmPrintValue(FILE* <replaceable>file</replaceable>, pmResult <replaceable>pmresult</replaceable>, <replaceable>pmdesc</replaceable>, <replaceable>vset_index</replaceable>, <replaceable>vlist_index</replaceable>, <replaceable>min_width</replaceable>)</literallayout> +<para><indexterm id="IG31340177435"><primary>pmFetch function</primary></indexterm><indexterm id="IG31340177436"><primary>pmPrintValue function</primary></indexterm>The value of a single performance metric (as identified by <replaceable>val</replaceable>) is printed on the standard I/O stream identified by <replaceable>f</replaceable>. The value of the performance metric is interpreted according to the format of <replaceable>val</replaceable> as defined by <replaceable>valfmt</replaceable> (from a <command>pmValueSet</command> within a <filename>pmResult</filename>) and the generic description of the metric's type from a <command>pmDesc</command> structure, passed in through.</para> +<para>If the converted value is less than <replaceable>minwidth</replaceable> characters wide, it will have leading spaces to pad the output to a width of <replaceable>minwidth</replaceable> characters.</para> +<para><xref linkend="Z976565414sdc"/> illustrates using <command>pmPrintValue</command> to print the values from a <filename>pmResult</filename> structure returned via <command>pmFetch</command>:</para> +<example id="Z976565414sdc"> +<title>Using <command>pmPrintValue</command> to Print Values</title> +<programlisting> int numpmid, i, j, sts; + pmID pmidlist[10]; + pmDesc desc[10]; + pmResult *result; + + /* set up PMAPI context, numpmid and pmidlist[] ... */ + /* get metric descriptors */ + for (i = 0; i < numpmid; i++) { + if ((sts = pmLookupDesc(pmidlist[i], &desc[i])) < 0) { + printf("pmLookupDesc(pmid=%s): %s\n", + pmIDStr(pmidlist[i]), pmErrStr(sts)); + exit(1); + } + } + if ((sts = pmFetch(numpmid, pmidlist, &result)) >= 0) { + /* once per metric */ + for (i = 0; i < result->numpmid; i++) { + printf("PMID: %s", pmIDStr(result->vset[i]->pmid)); + /* once per instance for this metric */ + for (j = 0; j < result->vset[i]->numval; j++) { + printf(" [%d]", result->vset[i]->vlist[j].inst); + pmPrintValue(stdout, result->vset[i]->valfmt, + desc[i].type, + &result->vset[i]->vlist[j], + 8); + } + putchar('\n'); + } + pmFreeResult(result); + } + else + printf("pmFetch: %s\n", pmErrStr(sts));</programlisting> +</example> +<para> +Print the value of a <replaceable>pmresult</replaceable> pointed to by <replaceable>vset_index</replaceable>/<replaceable>vlist_index</replaceable> and described by <replaceable>pmdesc</replaceable>. The format of a pmResult is described in <link linkend="IG31340177277"><emphasis>pmResult</emphasis></link> + +The python bindings can use sys.__stdout__ as a value for <replaceable>file</replaceable> to display to stdout. +</para> +</section> +<section id="id5211504"> + +<title><command>pmflush</command> Function</title> +<literallayout class="monospaced">int pmflush(void); +<command>Python:</command> +int <replaceable>status</replaceable> = pmflush()</literallayout> +<para><indexterm id="IG31340177437"><primary>pmflush function</primary></indexterm>The <command>pmflush</command> function causes the internal buffer which is shared with <command>pmprintf</command> to be either displayed in a window, printed on standard error, or flushed to a file and the internal buffer to be cleared.</para> +<para>The <literal>PCP_STDERR</literal> environment variable controls the output technique used by <command>pmflush</command>:</para> +<itemizedlist> +<listitem><para>If <literal>PCP_STDERR</literal> is unset, the text is written onto the stderr stream of the caller.</para> +</listitem> +<listitem><para>If <literal>PCP_STDERR</literal> is set to the literal reserved word <literal>DISPLAY</literal>, then the text is displayed as a GUI dialogue using <command>pmconfirm</command>.</para> +</listitem></itemizedlist> +<para>The <command>pmflush</command> function returns a value of zero on successful completion. A negative value is returned if an error was encountered, and this can be passed to <command>pmErrStr</command> to obtain the associated error message.</para> +</section> +<section id="id5211641"> + +<title><command>pmprintf</command> Function</title> +<literallayout class="monospaced">int pmprintf(const char *<replaceable>fmt</replaceable>, ... /*<replaceable>args</replaceable>*/); +<command>Python:</command> +pmprintf("fmt", ... /*<replaceable>args</replaceable>*/);</literallayout> +<para><indexterm id="IG31340177438"><primary>pmprintf function</primary></indexterm>The <command>pmprintf</command> function appends the formatted message string to an internal buffer shared by the <command>pmprintf</command> and <command>pmflush </command> functions, without actually producing any output. The <replaceable>fmt</replaceable> argument is used to control the conversion, formatting, and printing of the variable length <replaceable>args</replaceable> list.</para> +<para>The <command>pmprintf</command> function uses the <command>mkstemp</command> function to securely create a <literal>pcp</literal>-prefixed temporary file in <filename>${PCP_TMP_DIR}</filename>. This temporary file is deleted when <command>pmflush</command> is called.</para> +<para>On successful completion, <command>pmprintf</command> returns the number of characters transmitted. A negative value is returned if an error was encountered, and this can be passed to <command>pmErrStr</command> to obtain the associated error message.</para> +</section> +<section id="id5211762"> + +<title><command>pmSortInstances</command> Function</title> +<literallayout class="monospaced">void pmSortInstances(pmResult *<replaceable>result</replaceable>) +<command>Python:</command> +pmSortInstances (pmResult* pmresult)</literallayout> +<para><indexterm id="IG31340177439"><primary>pmSortInstances function</primary></indexterm><indexterm id="IG31340177440"><primary>pmFetch function</primary></indexterm>The <command>pmSortInstances</command> function may be used to guarantee that for each performance metric in the result from <command>pmFetch</command>, the instances are in ascending internal instance identifier sequence. This is useful when trying to compute rates from two consecutive <command>pmFetch</command> results, where the underlying instance domain or metric availability is not static.</para> +</section> +<section id="id5211834"> + +<title><command>pmParseInterval</command> Function</title> +<literallayout class="monospaced">int pmParseInterval(const char *<replaceable>string</replaceable>, struct timeval *<replaceable>rslt</replaceable>, char **<replaceable>errmsg</replaceable>) +<command>Python:</command> +(struct <replaceable>timeval</replaceable>, "error message") = pmParseInterval("time string")</literallayout> +<para><indexterm id="IG31340177441"><primary>pmParseInterval function</primary></indexterm>The <command>pmParseInterval</command> function parses the argument string specifying an interval of time and fills in the <literal>tv_sec</literal> and <literal>tv_usec</literal> components of the <filename>rslt</filename> structure to represent that interval. The input string is most commonly the argument following a <literal>-t</literal> command line option to a PCP application, and the syntax is fully described in the <command>PCPIntro(1)</command> man page.</para> +<para><command>pmParseInterval</command> returns 0 and <replaceable>errmsg</replaceable> is undefined if the parsing is successful. If the given string does not conform to the required syntax, the function returns -1 and a dynamically allocated error message string in <replaceable>errmsg</replaceable>.</para> +<para>The error message is terminated with a newline and includes the text of the input string along with an indicator of the position at which the error was detected as shown in the following example:</para> +<programlisting> 4minutes 30mumble + ^ -- unexpected value</programlisting> +<para>In the case of an error, the caller is responsible for calling <command>free</command> to release the space allocated for <replaceable>errmsg</replaceable>.</para> +</section> +<section id="id5211943"> + +<title><command>pmParseMetricSpec</command> Function</title> +<literallayout class="monospaced">int pmParseMetricSpec(const char *<replaceable>string</replaceable>, int <replaceable>isarch</replaceable>, char *<replaceable>source</replaceable>, + pmMetricSpec **<replaceable>rsltp</replaceable>, char **<replaceable>errmsg</replaceable>) +<command>Python:</command> +(pmMetricSpec <replaceable>metricspec</replaceable>, "error message") = + pmParseMetricSpec("metric specification", isarch, source)</literallayout> +<para><indexterm id="IG31340177442"><primary>pmParseMetricSpec function</primary></indexterm>The <command>pmParseMetricSpec</command> function accepts a <replaceable>string</replaceable> specifying the name of a PCP performance metric, and optionally the source (either a hostname, a PCP archive log filename, or a local context) and instances for that metric. The syntax is described in the <command>PCPIntro(1)</command> man page.</para> +<para>If neither host nor archive component of the metric specification is provided, the <literal>isarch</literal> and <literal>source</literal> arguments are used to fill in the returned <filename>pmMetricSpec</filename> structure. In <xref linkend="Z976566126sdc"/>, the <filename>pmMetricSpec</filename> structure, which is returned via <replaceable>rsltp,</replaceable> represents the parsed string.</para> +<example id="Z976566126sdc"> +<title><filename>pmMetricSpec</filename> Structure</title> +<programlisting>typedef struct { + int isarch; /* source type: 0 -> host, 1 -> archive, 2 -> local context */ + char *source; /* name of source host or archive */ + char *metric; /* name of metric */ + int ninst; /* number of instances, 0 -> all */ + char *inst[1]; /* array of instance names */ +} pmMetricSpec;</programlisting> +</example> +<para>The <command>pmParseMetricSpec</command> function returns 0 if the given string was successfully parsed. In this case, all the storage allocated by <command>pmParseMetricSpec</command> can be released by a single call to the <command>free</command> function by using the address returned from <command>pmMetricSpec</command> via <replaceable>rsltp</replaceable>. The convenience macro <command>pmFreeMetricSpec</command> is a thinly disguised wrapper for <command>free</command>.</para> +<para>The <command>pmParseMetricSpec</command> function returns 0 if the given string was successfully parsed. It returns <literal>PM_ERR_GENERIC</literal> and a dynamically allocated error message string in <replaceable>errmsg</replaceable> if the given string does not parse. In this situation, the error message string can be released with the <command>free</command> function.</para> +<para>In the case of an error, <replaceable>rsltp</replaceable> is undefined. In the case of success, <replaceable>errmsg</replaceable> is undefined. If <replaceable>rsltp</replaceable>-><replaceable>ninst</replaceable> is 0, then <replaceable>rsltp</replaceable>-><replaceable>inst</replaceable>[0] is undefined.</para> +</section> +</section> +</section> + +<section id="id5212196"> + +<title>PMAPI Programming Issues and Examples</title> +<para><indexterm id="IG31340177443"><primary>PMAPI</primary><secondary>programming issues</secondary></indexterm><indexterm id="IG31340177444"><primary>PMAPI</primary><secondary>programming issues</secondary></indexterm><indexterm id="IG31340177445"><primary>examples</primary><secondary>programming issues</secondary></indexterm>The following issues and examples are provided to enable you to create better custom performance monitoring tools.</para> +<para>The source code for a sample client (<command>pmclient</command>) using the PMAPI is shipped as part of the PCP package. See the <command>pmclient(1)</command> man page, and the source code, located in <filename>${PCP_DEMOS_DIR}/pmclient</filename>.</para> +<section id="id5212297"> + +<title>Symbolic Association between a Metric's Name and Value</title> +<para><indexterm id="IG31340177446"><primary>symbolic association</primary></indexterm><indexterm id="IG31340177447"><primary>metrics</primary><secondary>name and value</secondary></indexterm>A common problem in building specific performance tools is how to maintain the association between a performance metric's name, its access (instantiation) method, and the application program variable that contains the metric's value. Generally this results in code that is easily broken by bug fixes or changes in the underlying data structures. The PMAPI provides a uniform method for instantiating and accessing the values independent of the underlying implementation, although it does not solve the name-variable association problem. However, it does provide a framework within which a manageable solution may be developed.</para> +<para>Fundamentally, the goal is to be able to name a metric and reference the metric's value in a manner that is independent of the order of operations on other metrics; for example, to associate the <command>LOADAV</command> macro with the name <command>kernel.all.load</command>, and then be able to use <command>LOADAV</command> to get at the value of the corresponding metric.</para> +<para><indexterm id="IG31340177448"><primary>pmLookupName function</primary></indexterm><indexterm id="IG31340177449"><primary>pmFetch function</primary></indexterm>The one-to-one association between the ordinal position of the metric names is input to <command>pmLookupName</command> and the PMIDs returned by this function, and the one-to-one association between the PMIDs input to <command>pmFetch</command> and the values returned by this function provide the basis for an automated solution.</para> +<para>The tool <command>pmgenmap</command> takes the specification of a list of metric names and symbolic tags, in the order they should be passed to <command>pmLookupName</command> and <command>pmFetch</command>. For example, <command>pmclient</command>:</para> +<programlisting><userinput>cat ${PCP_DEMOS_DIR}/pmclient/pmnsmap.spec</userinput> +pmclient_init { + hinv.ncpu NUMCPU +} + +pmclient_sample { + kernel.all.load LOADAV + kernel.percpu.cpu.user CPU_USR + kernel.percpu.cpu.sys CPU_SYS + mem.freemem FREEMEM + disk.all.total DKIOPS +}</programlisting> +<para>This <command>pmgenmap</command> input produces the C code in <xref linkend="Z976566536sdc"/>. It is suitable for including with the <literal>#include</literal> statement:</para> +<example id="Z976566536sdc"> +<title>C Code Produced by <command>pmgenmap</command> Input</title> +<programlisting>/* + * Performance Metrics Name Space Map + * Built by runme.sh from the file + * pmnsmap.spec + * on Thu Jan 9 14:13:49 EST 2014 + * + * Do not edit this file! + */ + +char *pmclient_init[] = { +#define NUMCPU 0 + "hinv.ncpu", + +}; + + +char *pmclient_sample[] = { +#define LOADAV 0 + "kernel.all.load", +#define CPU_USR 1 + "kernel.percpu.cpu.user", +#define CPU_SYS 2 + "kernel.percpu.cpu.sys", +#define FREEMEM 3 + "mem.freemem", +#define DKIOPS 4 + "disk.all.total", + +};</programlisting> +</example> +</section> +<section id="id5212519"> + +<title>Initializing New Metrics</title> +<para><indexterm id="IG31340177450"><primary>PMAPI</primary><secondary>initializing new metrics</secondary></indexterm><indexterm id="IG31340177451"><primary>initialization</primary></indexterm><indexterm id="IG31340177452"><primary>new metrics</primary></indexterm>Using the code generated by <command>pmgenmap</command>, you are now able to easily initialize the application's metric specifications as shown in <xref linkend="Z976566793sdc"/>:</para> +<example id="Z976566793sdc"> +<title>Initializing Metric Specifications</title> +<programlisting>/* C code fragment from pmclient.c */ +numpmid = sizeof(pmclient_sample) / sizeof(char *); +if ((pmidlist = (pmID *)malloc(numpmid * sizeof(pmidlist[0]))) == NULL) {...} +if ((sts = pmLookupName(numpmid, pmclient_sample, pmidlist)) < 0) {...} +</programlisting> +<programlisting># The equivalent python code would be +pmclient_sample = ("kernel.all.load", "kernel.percpu.cpu.user", + "kernel.percpu.cpu.sys", "mem.freemem", "disk.all.total") +pmidlist = context.pmLookupName(pmclient_sample) +</programlisting> +</example> +<para>At this stage, <command>pmidlist</command> contains the PMID for the five metrics of interest.</para> +</section> +<section id="id5212595"> + +<title>Iterative Processing of Values</title> +<para><indexterm id="IG31340177453"><primary>PMAPI</primary><secondary>iterative processing</secondary></indexterm><indexterm id="IG31340177454"><primary>iterative processing</primary></indexterm>Assuming the tool is required to report values every <replaceable>delta</replaceable> seconds, use code similar to that in <xref linkend="Z976567058sdc"/>:</para> +<example id="Z976567058sdc"> +<title>Iterative Processing</title> +<programlisting>/* censored C code fragment from pmclient.c */ +while (samples == -1 || samples-- > 0) { + if ((sts = pmFetch(numpmid, pmidlist, &crp)) < 0) { ... } + for (i = 0; i < numpmid; i++) + if ((sts = pmLookupDesc(pmidlist[i], &desclist[i])) < 0) { ... } + ... + pmExtractValue(crp->vset[FREEMEM]->valfmt, crp->vset[FREEMEM]->vlist, + desclist[FREEMEM].type, &tmp, PM_TYPE_FLOAT); + pmConvScale(PM_TYPE_FLOAT, &tmp, &desclist[FREEMEM].units, + &atom, &mbyte_scale); + ip->freemem = atom.f; + ... + __pmtimevalSleep(delta); +}</programlisting> +<programlisting># The equivalent python code would be +FREEMEM = 3 +desclist = context.pmLookupDescs(metric_names) +while (samples > 0): + crp = context.pmFetch(metric_names) + val = context.pmExtractValue(crp.contents.get_valfmt(FREEMEM), + crp.contents.get_vlist(FREEMEM, 0), + desclist[FREEMEM].contents.type, + c_api.PM_TYPE_FLOAT) + atom = ctx.pmConvScale(c_api.PM_TYPE_FLOAT, val, desclist, FREEMEM, + c_api.PM_SPACE_MBYTE) + (tvdelta, errmsg) = c_api.pmParseInterval(delta) + c_api.pmtimevalSleep(delta) +</programlisting> +</example> +</section> +<section id="id5212682"> + +<title>Accommodating Program Evolution</title> +<para><indexterm id="IG31340177455"><primary>PMAPI</primary><secondary>program evolution</secondary></indexterm><indexterm id="IG31340177456"><primary>program evolution</primary></indexterm>The flexibility provided by the PMAPI and the <command>pmgenmap</command> utility is demonstrated by <xref linkend="Z976567218sdc"/>. Consider the requirement for reporting a third metric <literal>mem.physmem</literal>. This example shows how to add the line to the specification file:</para> +<example id="Z976567218sdc"> +<title>Adding a Metric</title> +<literallayout class="monospaced">mem.freemem PHYSMEM </literallayout> +<para>Then regenerate the <filename>#include</filename> file, and augment pmclient.c:</para> +<programlisting> pmExtractValue(crp->vset[PHYSMEM]->valfmt, crp->vset[PHYSMEM]->vlist, + desclist[PHYSMEM].type, &tmp, PM_TYPE_FLOAT); + pmConvScale(PM_TYPE_FLOAT, &tmp, &desclist[PHYSMEM].units, + &atom, &mbyte_scale); +</programlisting> +<programlisting># The equivalent python code would be: +val = context.pmExtractValue(crp.contents.get_valfmt(PHYSMEM), + crp.contents.get_vlist(PHYSMEM, 0), + desclist[PHYSMEM].contents.type, + c_api.PM_TYPE_FLOAT); +</programlisting> +</example> +</section> +<section id="id5212805"> + +<title>Handling PMAPI Errors</title> +<para><indexterm id="IG31340177457"><primary>PMAPI</primary><secondary>error handling</secondary></indexterm><indexterm id="IG31340177458"><primary>error handling</primary></indexterm>In <xref linkend="id5212839"/>, the simple but complete PMAPI application demonstrates the recommended style for handling PMAPI error conditions. The python bindings use the exception mechanism to raise an exception in error cases. The python client can handle this condition by catching the <literal>pmErr</literal> exception. For simplicity, no command line argument processing is shown here - in practice most tools use the <command>pmGetOptions</command> helper interface to assist with initial context creation and setup. +</para> +<example id="id5212839"> +<title>PMAPI Error Handling</title> +<programlisting>#include <pcp/pmapi.h> + +int +main(int argc, char* argv[]) +{ + int sts = 0; + char *host = "local:"; + char *metric = "mem.freemem"; + pmID pmid; + pmDesc desc; + pmResult *result; + + sts = pmNewContext(PM_CONTEXT_HOST, host); + if (sts < 0) { + fprintf(stderr, "Error connecting to pmcd on %s: %s\n", + host, pmErrStr(sts)); + exit(1); + } + sts = pmLookupName(1, &metric, &pmid); + if (sts < 0) { + fprintf(stderr, "Error looking up %s: %s\n", metric, + pmErrStr(sts)); + exit(1); + } + sts = pmLookupDesc(pmid, &desc); + if (sts < 0) { + fprintf(stderr, "Error getting descriptor for %s:%s: %s\n", + host, metric, pmErrStr(sts)); + exit(1); + } + sts = pmFetch(1, &pmid, &result); + if (sts < 0) { + fprintf(stderr, "Error fetching %s:%s: %s\n", host, metric, + pmErrStr(sts)); + exit(1); + } + sts = result->vset[0]->numval; + if (sts < 0) { + fprintf(stderr, "Error fetching %s:%s: %s\n", host, metric, + pmErrStr(sts)); + exit(1); + } + fprintf(stdout, "%s:%s = ", host, metric); + if (sts == 0) + puts("(no value)"); + else { + pmValueSet *vsp = result->vset[0]; + pmPrintValue(stdout, vsp->valfmt, desc.type, + &vsp->vlist[0], 5); + printf(" %s\n", pmUnitsStr(&desc.units)); + } + return 0; +}</programlisting> +<programlisting># The equivalent python code would be: +import sys +import traceback +from pcp import pmapi +from cpmapi import PM_TYPE_U32 + +try: + context = pmapi.pmContext() + pmid = context.pmLookupName("mem.freemem") + desc = context.pmLookupDescs(pmid) + result = context.pmFetch(pmid) + freemem = context.pmExtractValue(result.contents.get_valfmt(0), + result.contents.get_vlist(0, 0), + desc[0].contents.type, + PM_TYPE_U32) + print "freemem is " + str(int(freemem.ul)) + +except pmapi.pmErr, error: + print "%s: %s" % (sys.argv[0], error.message()) +except Exception, error: + sys.stderr.write(str(error) + "\n") + sys.stderr.write(traceback.format_exc() + "\n") +</programlisting> +</example> +</section> +<section id="id5212855"> + +<title>Compiling and Linking PMAPI Applications</title> +<para><indexterm id="IG31340177459"><primary>PMAPI</primary><secondary>application compiling </secondary></indexterm><indexterm id="IG31340177460"><primary>applications</primary><secondary>compiling </secondary></indexterm><indexterm id="IG31340177461"><primary>compiling and linking</primary></indexterm>Typical PMAPI applications require the following line to include the function prototype and data structure definitions used by the PMAPI. </para> +<programlisting>#include <pcp/pmapi.h></programlisting> +<para>Some applications may also require these header files: <filename><pcp/impl.h></filename> and <filename><pcp/pmda.h></filename>.</para> +<para>The run-time environment of the PMAPI is mostly found in the <filename>libpcp</filename> library; so to link a generic PMAPI application requires something akin to the following command:</para> +<literallayout class="monospaced"><userinput>cc</userinput> <replaceable>mycode</replaceable><userinput>.c -lpcp</userinput></literallayout> +</section> +</section> +</chapter> + + +<chapter id="LE25915-PARENT"> + +<title>Instrumenting Applications</title> +<para><indexterm id="IG31340177462nat"><primary>MMV PMDA</primary><secondary>description</secondary></indexterm><indexterm id="IG31340177462"><primary>trace PMDA</primary><secondary>description</secondary></indexterm><indexterm id="IG31340177463"><primary>PMDA</primary><secondary>trace</secondary></indexterm>This chapter provides an introduction to ways of instrumenting applications using PCP.</para> +<para><indexterm id="IG31340177565"><primary>customization</primary></indexterm> The first section covers the use of the Memory Mapped Value (MMV) Performance Metrics Domain Agent (PMDA) to generate customized metrics from an application. This provides a robust, extremely efficient mechanism for transferring custom instrumentation into the PCP infrastructure. It has been successfully deployed in production environments for many years, has proven immensely valuable in these situations, and can be used to instrument applications written in a number of programming languages.</para> +<para>The Memory Mapped Value library and PMDA is supported on every PCP platform, and is enabled by default.</para> +<note><para>A particularly expansive Java API is available from the separate +<ulink url="http://code.google.com/p/parfait/">Parfait</ulink> +project. It supports both the existing JVM instrumentation, and custom application metric extensions.</para></note> +<para> <indexterm id="IG31340177464nat"><primary>libpcp_mmv library</primary><secondary>instrumenting applications</secondary></indexterm><indexterm id="IG31340177465nat"><primary>examples</primary><secondary>MMV PMDA</secondary></indexterm> The chapter also includes information on how to use the MMV library (<filename>libpcp_mmv</filename>) for instrumenting an application. The example programs are installed in <filename>${PCP_DEMOS_DIR}/mmv</filename>.</para> +<para>The second section covers the design of the Trace PMDA, in an effort to explain how to configure the agent optimally for a particular problem domain. This information supplements the functional coverage which the man pages provide to both the agent and the library interfaces.</para> +<para> <indexterm id="IG31340177464"><primary>libpcp_trace library</primary><secondary>instrumenting applications</secondary></indexterm><indexterm id="IG31340177465"><primary>examples</primary><secondary>trace PMDA</secondary></indexterm> This part of the chapter also includes information on how to use the Trace PMDA and its associated library (<filename>libpcp_trace</filename>) for instrumenting applications. The example programs are installed in <filename>${PCP_DEMOS_DIR}/trace</filename>.</para> +<warning><para>The current PCP trace library is a relatively heavy-weight solution, issuing multiple system calls per trace point, runs over a TCP/IP socket even locally and performs no event batching. As such it is not appropriate for production application instrumentation at this stage.</para></warning> +<para>A revised application tracing library and PMDA are planned which will be light-weight, suitable for production system tracing, and support event metrics and other advances in end-to-end distributed application tracing.</para> +<para><indexterm id="IG31340177554"><primary>application developers</primary></indexterm> <indexterm id="IG31340177555"><primary>embedded calls</primary></indexterm>The application instrumentation libraries are designed to encourage application developers to embed calls in their code that enable application performance data to be exported. When combined with system-level performance data, this feature allows total performance and resource demands of an application to be correlated with application activity.</para> +<para>For example, developers can provide the following application performance metrics:</para> +<itemizedlist> +<listitem><para><indexterm id="IG31340177556"><primary>computation state</primary></indexterm>Computation state (especially for codes with major shifts in resource demands between phases of their execution)</para> +</listitem> +<listitem><para><indexterm id="IG31340177557"><primary>parallelism</primary></indexterm>Problem size and parameters, that is, degree of parallelism throughput in terms of sub-problems solved, iteration count, transactions, data sets inspected, and so on</para> +</listitem> +<listitem><para><indexterm id="IG31340177558"><primary>service time</primary></indexterm>Service time by operation type</para> +</listitem></itemizedlist> +<section id="id5213105"> + +<title>Application and Performance Co-Pilot Relationship</title> +<para><indexterm id="IG31340177550"><primary>applications</primary><secondary>instrumentation</secondary></indexterm><indexterm id="IG31340177551"><primary>instrumentation</primary></indexterm> <indexterm id="IG31340177552"><primary>data export</primary></indexterm>The relationship between an application, the <filename>pcp_mmv</filename> and <filename>pcp_trace</filename> instrumentation libraries, the MMV and Trace PMDAs, and the rest of the PCP infrastructure is shown in <xref linkend="id5216302"/>:</para> +<para><figure id="id5216302"><title>Application and PCP Relationship</title><mediaobject><imageobject><imagedata fileref="figures/instrumentation.svg"/></imageobject><textobject><phrase>Application and PCP Relationship</phrase></textobject></mediaobject></figure></para> +<para>Once the application performance metrics are exported into the PCP framework, all of the PCP tools may be leveraged to provide performance monitoring and management, including:</para> +<itemizedlist> +<listitem><para>Two- and three-dimensional visualization of resource demands and performance, showing concurrent system activity and application activity.</para> +</listitem> +<listitem><para><indexterm id="IG31340177561"><primary>distributed performance management</primary><secondary>data transportation</secondary></indexterm>Transport of performance data over the network for distributed performance management.</para> +</listitem> +<listitem><para><indexterm id="IG31340177562"><primary>archive logs</primary><secondary>performance management</secondary></indexterm>Archive logging for historical records of performance, most useful for problem diagnosis, postmortem analysis, performance regression testing, capacity planning, and benchmarking.</para> +</listitem> +<listitem><para><indexterm id="IG31340177563"><primary>automated alarms</primary></indexterm>Automated alarms when bad performance is observed. These apply both in real-time or when scanning archives of historical application performance.</para> +</listitem></itemizedlist> +</section> +<section id="id5213104"> + +<title>Performance Instrumentation and Sampling</title> +<para><indexterm id="IG31340177467nat"><primary>performance instrumentation</primary></indexterm><indexterm id="IG31340177468nat"><primary>instrumentation</primary></indexterm>The <filename>pcp_mmv</filename> library provides function calls to assist with extracing important performance metrics from a program into a shared, in-memory location such that the MMV PMDA can examine and serve that information on behalf of PCP client tool requests. The <filename>pcp_mmv</filename> library is described in the <command>mmv_stats_init(3)</command>, <command>mmv_lookup_value_desc(3)</command>, <command>mmv_inc_value(3)</command> man pages. Additionally, the format of the shared memory mappings is described in detail in <command>mmv(5)</command>.</para> +</section> +<section id="id5213287nat"> + +<title>MMV PMDA Design</title> +<para><indexterm id="IG31340177470nat"><primary>MMV PMDA</primary><secondary>design</secondary></indexterm>An application instrumented with memory mapped values directly updates the memory that backs the metric values it exports. The MMV PMDA reads those values directly, from the <literal>same</literal> memory that the application is updating, when current values are sampled on behalf of PMAPI client tools. This relationship, and a simplified MMV API, are shown in <xref linkend="id5214410nat"/>.</para> +<para><figure id="id5214410nat"><title>Memory Mapped Page Sharing</title><mediaobject><imageobject><imagedata fileref="figures/pmdammv.svg"/></imageobject></mediaobject></figure></para> +<para>It is worth noting that once the metrics of an application have been registered via the <filename>pcp_mmv</filename> library initialisation API, subsequent interactions with the library are not intrusive to the instrumented application. At the points where values are updated, the only cost involved is the memory mapping update, which is a single memory store operation. There is no need to explicitly transfer control to the MMV PMDA, nor allocate memory, nor make system or library calls. The PMDA will only sample the values at times driven by PMAPI client tools, and this places no overhead on the instrumented application.</para> +</section> +<section id="id5213288nat"> + +<title>Memory Mapped Values API</title> +<para><indexterm id="IG31340177502nat"><primary>Application Programming Interface</primary></indexterm> <indexterm id="IG31340177503nat"><primary>libpcp_mmv library</primary><secondary>Application Programming Interface</secondary></indexterm>The <filename>libpcp_mmv</filename> Application Programming Interface (API) can be called from C, C++, Perl and Python (a separate project, Parfait, services the needs of Java applications). Each language has access to the complete set of functionality offered by <filename>libpcp_mmv</filename>. In most cases, the calling conventions differ only slightly between languages - in the case of Java and Parfait, they differ significantly however.</para> +<section id="id5214320nat"> + +<title>Starting and Stopping Instrumentation</title> +<para><indexterm id="IG31340177504nat"><primary>mmv_stats_init function</primary></indexterm> <indexterm id="IG31340177505nat"><primary>mmv_stats_stop function</primary></indexterm> +Instrumentation is begun with an initial call to <literal>mmv_stats_init</literal>, and ended with a call to <literal>mmv_stats_stop</literal>. These calls manipulate global state shared by the library and application. These are the only calls requiring synchonization and a single call to each is typically performed early and late in the life of the application (although they can be used to reset the library state as well, at any time). As such, the choice of synchonization primitive is left to the application, and none is currently performed by the library.</para> +<literallayout class="monospaced">void *mmv_stats_init(const char *<replaceable>name</replaceable>, int <replaceable>cluster</replaceable>, mmv_stats_flags_t <replaceable>flags</replaceable>, + const mmv_metric_t *<replaceable>stats</replaceable>, int <replaceable>nstats</replaceable>, + const mmv_indom_t *<replaceable>indoms</replaceable>, int <replaceable>nindoms</replaceable>)</literallayout> +<para>The <replaceable>name</replaceable> should be a simple symbolic name identifying the application. It is usually used as the first application-specific part of the exported metric names, as seen from the MMV PMDA. This behavior can be overriden using the <replaceable>flags</replaceable> parameter, with the MMV_FLAG_NOPREFIX flag. In the example below, full metric names such as <literal>mmv.acme.products.count</literal> will be created by the MMV PMDA. With the MMV_FLAG_NOPREFIX flag set, that would instead become <literal>mmv.products.count</literal>. It is recommended to not disable the prefix - doing so requires the applications to ensure naming conflicts do not arise in the MMV PMDA metric names.</para> +<para>The <replaceable>cluster</replaceable> identifier is used by the MMV PMDA to further distinguish different applications, and is directly used for the MMV PMDA PMID cluster field described in <xref linkend="Z1033577630tls"/>, for all MMV PMDA metrics.</para> +<para>All remaining parameters to <literal>mmv_stats_init</literal> define the metrics and instance domains that exist within the application. These are somewhat analagous to the final parameters of <literal>pmdaInit(3)</literal>, and are best explained using <xref linkend="Z1033577630nat"/> and <xref linkend="Z1033577631nat"/>. As mentioned earlier, the full source code for this example instrumented application can be found in <filename>${PCP_DEMOS_DIR}/mmv</filename>.</para> +<para><example id="Z1033577630nat"> +<title>Memory Mapped Value Instance Structures</title> +<programlisting>#include <pcp/pmapi.h> +#include <pcp/mmv_stats.h> + +static mmv_instances_t products[] = { + { .internal = 0, .external = "Anvils" }, + { .internal = 1, .external = "Rockets" }, + { .internal = 2, .external = "Giant_Rubber_Bands" }, +}; +#define ACME_PRODUCTS_INDOM 61 +#define ACME_PRODUCTS_COUNT (sizeof(products)/sizeof(products[0])) + +static mmv_indom_t indoms[] = { + { .serial = ACME_PRODUCTS_INDOM, + .count = ACME_PRODUCTS_COUNT, + .instances = products, + .shorttext = "Acme products", + .helptext = "Most popular products produced by the Acme Corporation", + }, +};</programlisting> +</example></para> +<para>The above data structures initialize an instance domain +of the set of products produced in a factory by the fictional +"Acme Corporation". These structures are directly comparable to +several concepts we have seen already (and for good reason - the +MMV PMDA must interpret the applications intentions and properly +export instances on its behalf):</para> +<itemizedlist> +<listitem><para>mmv_instances_t maps to pmdaInstid, as in <xref linkend="Z975964618sdc"/></para> +</listitem> +<listitem><para>mmv_indom_t maps to pmdaIndom, as in <xref linkend="Z975964773sdc"/> - the +major difference is the addition of oneline and long help text, the purpose of which should +be self-explanatory at this stage.</para> +</listitem> +<listitem><para><replaceable>serial</replaceable> numbers, as in <xref linkend="Z1033578294tls"/></para> +</listitem> +</itemizedlist> +<para>Next, we shall create three metrics, all of which use this instance domain. +These are the <literal>mmv.acme.products</literal> metrics, and they reflect the +rates at which products are built by the machines in the factory, how long these +builds take for each product, and how long each product type spends queued (while +waiting for factory capacity to become available).</para> +<para><example id="Z1033577631nat"> +<title>Memory Mapped Value Metrics Structures</title> +<programlisting>static mmv_metric_t metrics[] = { + { .name = "products.count", + .item = 7, + .type = MMV_TYPE_U64, + .semantics = MMV_SEM_COUNTER, + .dimension = MMV_UNITS(0,0,1,0,0,PM_COUNT_ONE), + .indom = ACME_PRODUCTS_INDOM, + .shorttext = "Acme factory product throughput", + .helptext = +"Monotonic increasing counter of products produced in the Acme Corporation\n" +"factory since starting the Acme production application. Quality guaranteed.", + }, + { .name = "products.time", + .item = 8, + .type = MMV_TYPE_U64, + .semantics = MMV_SEM_COUNTER, + .dimension = MMV_UNITS(0,1,0,0,PM_TIME_USEC,0), + .indom = ACME_PRODUCTS_INDOM, + .shorttext = "Machine time spent producing Acme products", + .helptext = +"Machine time spent producing Acme Corporation products. Does not include\n" +"time in queues waiting for production machinery.", + }, + { .name = "products.queuetime", + .item = 10, + .type = MMV_TYPE_U64, + .semantics = MMV_SEM_COUNTER, + .dimension = MMV_UNITS(0,1,0,0,PM_TIME_USEC,0), + .indom = ACME_PRODUCTS_INDOM, + .shorttext = "Queued time while producing Acme products", + .helptext = +"Time spent in the queue waiting to build Acme Corporation products,\n" +"while some other Acme product was being built instead of this one.", + }, +}; +#define INDOM_COUNT (sizeof(indoms)/sizeof(indoms[0])) +#define METRIC_COUNT (sizeof(metrics)/sizeof(metrics[0]))</programlisting> +</example></para> +<para>As was the case with the "products" instance domain before, these metric-defining +data structures are directly comparable to PMDA data structures described earlier:</para> +<itemizedlist> +<listitem><para>mmv_metric_t maps to a pmDesc structure, as in <xref linkend="Z975964618sdc"/></para> +</listitem> +<listitem><para>MMV_TYPE, MMV_SEM, and MMV_UNITS map to PMAPI constructs for type, semantics, dimensionality and scale, as in <xref linkend="Z1034792511tls"/></para> +</listitem> +<listitem><para><replaceable>item</replaceable> number, as in <xref linkend="Z1033577630tls"/></para> +</listitem> +</itemizedlist> +<para>For the most part, all types and macros map directly to their core PCP counterparts, which the MMV PMDA will use when exporting the metrics. One important exception is the introduction of the metric type MMV_TYPE_ELAPSED, which is discussed further in <xref linkend="id5214734"/>.</para> +<para>The compound metric types - aggregate and event type metrics - are not supported by the MMV format.</para> +</section> + +<section> +<title>Getting a Handle on Mapped Values</title> +<para><indexterm id="Z1033577633nat"><primary>mmv_lookup_value_desc function</primary></indexterm>Once metrics (and the instance domains they use) have been registered, the memory mapped file has been created and is ready for use. In order to be able to update the individual metric values, however, we must find get a handle to the value. This is done using the <command>mmv_lookup_value_desc</command> function, as shown in <xref linkend="Z1033577632nat"/>.</para> +<para><example id="Z1033577632nat"> +<title>Memory Mapped Value Handles</title> +<programlisting>#define ACME_CLUSTER 321 /* PMID cluster identifier */ + +int +main(int argc, char * argv[]) +{ + void *base; + pmAtomValue *count[ACME_PRODUCTS_COUNT]; + pmAtomValue *machine[ACME_PRODUCTS_COUNT]; + pmAtomValue *inqueue[ACME_PRODUCTS_COUNT]; + unsigned int working; + unsigned int product; + unsigned int i; + + base = mmv_stats_init("acme", ACME_CLUSTER, 0, + metrics, METRIC_COUNT, indoms, INDOM_COUNT); + if (!base) { + perror("mmv_stats_init"); + return 1; + } + + for (i = 0; i < ACME_PRODUCTS_COUNT; i++) { + count[i] = mmv_lookup_value_desc(base, + "products.count", products[i].external); + machine[i] = mmv_lookup_value_desc(base, + "products.time", products[i].external); + inqueue[i] = mmv_lookup_value_desc(base, + "products.queuetime", products[i].external); + }</programlisting> +</example></para> +<para>Space in the mapping file for every value is set aside at initialization time (by the <command>mmv_stats_init</command> function) - that is, space for each and every metric, and each value (instance) of each metric when an instance domain is used. To find the handle to the space set aside for one individual value requires the tuple of base memory address of the mapping, metric name, and instance name. In the case of metrics with no instance domain, the final instance name parameter should be either NULL or the empty string.</para> +</section> +<section> + +<title>Updating Mapped Values</title> +<para><indexterm id="Z1033577634nat"><primary>mmv_stats_inc function</primary></indexterm>At this stage we have individual handles (pointers) to each instrumentation point, we can now start modifying these values and observing changes through the PCP infrastructure. Notice that each handle is simply the canonical <command>pmAtomValue</command> pointer, as defined in <xref linkend="Z976562908sdc"/>, which is a union providing sufficient space to hold any single value.</para> +<para>This pointer can be either manipulated directly, or using helper functions provided by the <command>pcp_mmv</command> API, such as the <command>mmv_stats_inc</command> and <command>mmv_stats_set</command> functions.</para> +<para><example id="Z1033577636"> +<title>Memory Mapped Value Updates</title> +<programlisting> while (1) { + /* choose a random number between 0-N -> product */ + product = rand() % ACME_PRODUCTS_COUNT; + + /* assign a time spent "working" on this product */ + working = rand() % 50000; + + /* pretend to "work" so process doesn't burn CPU */ + usleep(working); + + /* update the memory mapped values for this one: */ + /* one more product produced and work time spent */ + mmv_inc_value(base, machine[product], working); /* API */ + count[product]->ull += 1; /* or direct mmap update */ + + /* all other products are "queued" for this time */ + for (i = 0; i < ACME_PRODUCTS_COUNT; i++) + if (i != product) + mmv_inc_value(base, inqueue[i], working); + }</programlisting> +</example></para> +<para>At this stage, it will be informative to compile and run the complete example program, which can be found in <filename>${PCP_DEMOS_DIR}/mmv/acme.c</filename>. There is an associated <filename>Makefile</filename> to build it, in the same directory. Running the <filename>acme</filename> binary creates the instrumentation shown in <xref linkend="Z1033577637"/>, with live values letting us explore simple queueing effects in products being created on the ACME factory floor.</para> +<para><example id="Z1033577637"> +<title>Memory Mapped Value Reports</title> +<programlisting><userinput>pminfo -m mmv.acme</userinput> +mmv.acme.products.queuetime PMID: 70.321.10 +mmv.acme.products.time PMID: 70.321.8 +mmv.acme.products.count PMID: 70.321.7 + +<userinput>pmval -f2 -s3 mmv.acme.products.time</userinput> +metric: mmv.acme.products.time +host: localhost +semantics: cumulative counter (converting to rate) +units: microsec (converting to time utilization) +samples: 3 +interval: 1.00 sec + + Anvils Rockets Giant_Rubber_Bands + 0.37 0.12 0.50 + 0.35 0.25 0.38 + 0.57 0.20 0.23</programlisting> +</example></para> +<para>Experimentation with the algorithm from <xref linkend="Z1033577636"/> is encouraged. In particular, observe the effects of rate conversion (counter metric type) of a metric with units of "time" (PM_TIME_*). The reported values are calculated over a sampling interval, which also has units of "time", forming a utilization. This is extremely valuable performance analysis currency - comparable metrics would include processor utilization, disk spindle utilization, and so forth.</para> +</section> + +<section id="id5214734"> +<title>Elapsed Time Measures</title> +<para><indexterm id="Z1033577635nat"><primary>mmv_stats_interval_start function</primary></indexterm><indexterm id="Z1033577636nat"><primary>mmv_stats_interval_end function</primary></indexterm>One problem with the instrumentation model embodied by the <command>pcp_mmv</command> library is providing timing information for long-running operations. For instrumenting long-running operations, like uploading downloading a file, the overall operation may be broken into smaller, discrete units of work which can be easily instrumented in terms of operations and througput measures. In other cases, there are no divisible units for long-running operations (for example a black-box library call) and instrumenting these operations presents a challenge. Sometimes the best that can be done is adding the instrumentation point at the completion of the operation, and simply accept the "bursty" nature of this approach. In these problematic cases, the work completed in one sampling-interval may have begun several intervals before, from the point of view of the monitoring tool, which can lead to misleading results.</para> +<para>One technique that is available to combat this is through use of the MMV_TYPE_ELAPSED metric type, which provides the concept of a "timed section" of code. This mechanism stores the start time of an operation along with the mapped metric value (an "elapsed time" counter), via the <command>mmv_stats_interval_start</command> instrumentation function. Then, with help from the MMV PMDA which recognizes this type, the act of sampling the metric value causes an <emphasis role="bold">interim</emphasis> timestamp to be taken (by the MMV PMDA, not the application) and <emphasis role="bold">combined</emphasis> with the initial timestamp to form a more accurate reflection of time spent within the timed section, which effectively smooths out the bursty nature of the instrumentation.</para> +<para>The completion of each timed section of code is marked by a call to <command>mmv_stats_interval_end</command> which signifies to the MMV PMDA that the operation is not active, and no extra "in-progress" time should be applied to the exported value. At that time, the elapsed time for the entire operation is calculated and accounted toward metrics value.</para> +</section> + +</section> +<section id="id5213106"> + +<title>Performance Instrumentation and Tracing</title> +<para><indexterm id="IG31340177466"><primary>pmdatrace man page</primary></indexterm><indexterm id="IG31340177467"><primary>performance instrumentation</primary></indexterm><indexterm id="IG31340177468"><primary>instrumentation</primary></indexterm>The <filename>pcp_trace</filename> library provides function calls for identifying sections of a program as transactions or events for examination by the trace PMDA, a user command called <command>pmdatrace</command>. The <filename>pcp_trace</filename> library is described in the <command>pmdatrace(3)</command> man page</para> +<para>The monitoring of transactions using the Performance Co-Pilot (PCP) infrastructure begins with a <command>pmtracebegin</command> call. Time is recorded from there to the corresponding <command>pmtraceend</command> call (with matching tag identifier). A transaction in progress can be cancelled by calling <command>pmtraceabort</command>.</para> +<para>A second form of program instrumentation is available with the <command>pmtracepoint</command> function. This is a simpler form of monitoring that exports only the number of times a particular point in a program is passed. The <command>pmtraceobs</command> and <command>pmtracecount</command> functions have similar semantics, but the former allows an arbitrary numeric value to be passed to the trace PMDA.</para> +<para><indexterm id="IG31340177469"><primary>pmdatrace man page</primary></indexterm>The <command>pmdatrace</command> command is a PMDA that exports transaction performance metrics from application processes using the <filename>pcp_trace</filename> library; see the <command>pmdatrace(1)</command> man page for details.</para> +</section> +<section id="id5213287"> + +<title>Trace PMDA Design</title> +<para><indexterm id="IG31340177470"><primary>trace PMDA</primary><secondary>design</secondary></indexterm>Trace PMDA design covers application interaction, sampling techniques, and configuring the trace PMDA.</para> +<section id="id5213308"> + +<title>Application Interaction</title> +<para><indexterm id="IG31340177471"><primary>applications</primary><secondary>interaction</secondary></indexterm><xref linkend="id5213335"/> describes the general state maintained within the trace PMDA.</para> +<para><figure id="id5213335"><title>Trace PMDA Overview</title><mediaobject><imageobject><imagedata fileref="figures/trace.svg"/></imageobject><textobject><phrase>Trace PMDA Overview</phrase></textobject></mediaobject></figure></para> +<para><indexterm id="IG31340177472"><primary>Application Programming Interface</primary></indexterm> <indexterm id="IG31340177473"><primary> identification tags</primary></indexterm> <indexterm id="IG31340177474"><primary>IPC</primary><secondary>trace API</secondary></indexterm>Applications that are linked with the <filename>libpcp_trace</filename> library make calls through the trace Application Programming Interface (API). These calls result in interprocess communication of trace data between the application and the trace PMDA. This data consists of an identification tag and the performance data associated with that particular tag. The trace PMDA aggregates the incoming information and periodically updates the exported summary information to describe activity in the recent past.</para> +<para><indexterm id="IG31340177475"><primary>PDU</primary></indexterm> <indexterm id="IG31340177476"><primary>working buffers</primary></indexterm>As each protocol data unit (PDU) is received, its data is stored in the current working buffer. At the same time, the global counter associated with the particular tag contained within the PDU is incremented. The working buffer contains all performance data that has arrived since the previous time interval elapsed. For additional information about the working buffer, see <xref linkend="LE42586-PARENT"/>.</para> +</section> +<section id="id5213449"> + +<title>Sampling Techniques</title> +<para><indexterm id="IG31340177477"><primary>rolling-window sampling</primary></indexterm> <indexterm id="IG31340177478"><primary>sampling techniques</primary></indexterm>The trace PMDA employs a rolling-window periodic sampling technique. The arrival time of the data at the trace PMDA in conjunction with the length of the sampling period being maintained by the PMDA determines the recency of the data exported by the PMDA. Through the use of rolling-window sampling, the trace PMDA is able to present a more accurate representation of the available trace data at any given time than it could through use of simple periodic sampling.</para> +<para> <indexterm id="IG31340177479"><primary>trace.observe.rate metric</primary></indexterm> <indexterm id="IG31340177480"><primary>trace.point.rate metric</primary></indexterm> <indexterm id="IG31340177481"><primary>trace.transact.ave_time metric</primary></indexterm> <indexterm id="IG31340177482"><primary>trace.transact.max_time metric</primary></indexterm> <indexterm id="IG31340177483"><primary>trace.transact.min_time metric</primary></indexterm> <indexterm id="IG31340177484"><primary>trace.transact.rate metric</primary></indexterm>The rolling-window sampling technique affects the metrics in <xref linkend="Z976568222sdc"/>:</para> +<example id="Z976568222sdc"> +<title>Rolling-Window Sampling Technique</title> +<literallayout class="monospaced">trace.observe.rate +trace.counter.rate +trace.point.rate +trace.transact.ave_time +trace.transact.max_time +trace.transact.min_time +trace.transact.rate</literallayout> +</example> +<para>The remaining metrics are either global counters, control metrics, or the last seen observation value. <xref linkend="LE26087-PARENT"/>, documents in more detail all metrics exported by the trace PMDA.</para> +<section id="id5213576"> + +<title>Simple Periodic Sampling</title> +<para><indexterm id="IG31340177485"><primary>periodic sampling</primary></indexterm><indexterm id="IG31340177486"><primary>simple periodic sampling</primary></indexterm> <indexterm id="IG31340177487"><primary>historical buffers</primary></indexterm>The simple periodic sampling technique uses a single historical buffer to store the history of events that have occurred over the sampling interval. As events occur, they are recorded in the working buffer. At the end of each sampling interval, the working buffer (which at that time holds the historical data for the sampling interval just finished) is copied into the historical buffer, and the working buffer is cleared. It is ready to hold new events from the sampling interval now starting.</para> +</section> +<section id="LE42586-PARENT"> + +<title>Rolling-Window Periodic Sampling</title> +<para><indexterm id="IG31340177488"><primary>rolling-window sampling</primary></indexterm>In contrast to simple periodic sampling with its single historical buffer, the rolling-window periodic sampling technique maintains a number of separate buffers. One buffer is marked as the current working buffer, and the remainder of the buffers hold historical data. As each event occurs, the current working buffer is updated to reflect it.</para> +<para>At a specified interval, the current working buffer and the accumulated data that it holds is moved into the set of historical buffers, and a new working buffer is used. The specified interval is a function of the number of historical buffers maintained.</para> +<para>The primary advantage of the rolling-window sampling technique is seen at the point where data is actually exported. At this point, the data has a higher probability of reflecting a more recent sampling period than the data exported using simple periodic sampling.</para> +<para><indexterm id="IG31340177489"><primary>sample duration</primary></indexterm>The data collected over each sample duration and exported using the rolling-window sampling technique provides a more up-to-date representation of the activity during the most recently completed sample duration than simple periodic sampling as shown in <xref linkend="id5213739"/>.</para> +<para><figure id="id5213739"><title>Sample Duration Comparison</title><mediaobject><imageobject><imagedata fileref="figures/trace-sampling.svg"/></imageobject><textobject><phrase>Sample Duration Comparison</phrase></textobject></mediaobject></figure></para> +<para><indexterm id="IG31340177490"><primary>ring buffers</primary></indexterm>The trace PMDA allows the length of the sample duration to be configured, as well as the number of historical buffers that are maintained. The rolling-window approach is implemented in the trace PMDA as a ring buffer (see <xref linkend="id5213335"/>).</para> +<para><indexterm id="IG31340177491"><primary>working buffers</primary></indexterm> <indexterm id="IG31340177492"><primary>historical buffers</primary></indexterm>When the current working buffer is moved into the set of historical buffers, the least recent historical buffer is cleared of data and becomes the new working buffer.</para> +</section> +<section id="id5213803"> + +<title>Rolling-Window Periodic Sampling Example</title> +<para><indexterm id="IG31340177493"><primary>examples</primary><secondary>rolling-window sampling</secondary></indexterm>Consider the scenario where you want to know the rate of transactions over the last 10 seconds. You set the sampling rate for the trace PMDA to 10 seconds and fetch the metric <literal>trace.transact.rate</literal>. So if in the last 10 seconds, 8 transactions took place, the transaction rate would be 8/10 or 0.8 transactions per second.</para> +<para>The trace PMDA does not actually do this. It instead does its calculations automatically at a subinterval of the sampling interval. Reconsider the 10-second scenario. It has a calculation subinterval of 2 seconds as shown in <xref linkend="id5213848"/>.</para> +<para><figure id="id5213848"><title>Sampling Intervals</title><mediaobject><imageobject><imagedata fileref="figures/trace-example.svg"/></imageobject><textobject><phrase>Sampling Intervals</phrase></textobject></mediaobject></figure></para> +<para>If at 13.5 seconds, you request the transaction rate, you receive a value of 0.7 transactions per second. In actual fact, the transaction rate was 0.8, but the trace PMDA did its calculations on the sampling interval from 2 seconds to 12 seconds, and not from 3.5 seconds to 13.5 seconds. For efficiency, the trace PMDA calculates the metrics on the last 10 seconds every 2 seconds. As a result, the PMDA is not driven each time a fetch request is received to do a calculation.</para> +</section> +</section> +<section id="id5213903"> + +<title>Configuring the Trace PMDA</title> +<para><indexterm id="IG31340177494"><primary>trace PMDA</primary><secondary>command-line options</secondary></indexterm>The trace PMDA is configurable primarily through command-line options. The list of command-line options in <xref linkend="id5213936"/> is not exhaustive, but it identifies those options which are particularly relevant to tuning the manner in which performance data is collected.</para> +<table id="id5213936" frame="topbot"> + +<title>Selected Command-Line Options</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="149*"/> +<colspec colwidth="247*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Option</para></entry><entry align="left" valign="bottom"><para>Description</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para>Access controls<indexterm id="IG31340177495"><primary>access controls</primary></indexterm></para></entry> +<entry align="left" valign="top"><para>The trace PMDA offers host-based access control. This control allows and disallows connections from instrumented applications running on specified hosts or groups of hosts. Limits to the number of connections allowed from individual hosts can also be mandated.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>Sample duration<indexterm id="IG31340177496"><primary>sample duration</primary></indexterm></para></entry> +<entry align="left" valign="top"><para>The interval over which metrics are to be maintained before being discarded is called the sample duration.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>Number of historical buffers<indexterm id="IG31340177497"><primary>historical buffers</primary></indexterm></para></entry> +<entry align="left" valign="top"><para>The data maintained for the sample duration is held in a number of internal buffers within the trace PMDA. These are referred to as historical buffers. This number is configurable so that the rolling window effect can be tuned within the sample duration.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>Counter and observation metric units<indexterm id="IG31340177498"><primary>observation metric units</primary></indexterm></para></entry> +<entry align="left" valign="top"><para><indexterm id="IG31340177499"><primary>pmchart command</primary></indexterm> Since the data being exported by the <literal>trace.observe.value</literal> and <literal>trace.counter.count</literal> metrics are user-defined, the trace PMDA by default exports these metrics with a type of “none.” A framework is provided that allows the user to make the type more specific (for example, bytes per second) and allows the exported values to be plotted along with other performance metrics of similar units by tools like <command>pmchart</command>.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>Instance domain refresh<indexterm id="IG31340177500"><primary>instance domain refresh</primary></indexterm></para></entry> +<entry align="left" valign="top"><para>The set of instances exported for each of the <literal>trace</literal> metrics can be cleared through the storable <literal><indexterm id="IG31340177501"><primary>trace.control.reset metric</primary></indexterm> trace.control.reset</literal> metric.</para></entry></row></tbody></tgroup></table> +</section> +</section> +<section id="LE26087-PARENT"> + +<title>Trace API</title> +<para><indexterm id="IG31340177502"><primary>Application Programming Interface</primary></indexterm> <indexterm id="IG31340177503"><primary>libpcp_trace library</primary><secondary>Application Programming Interface</secondary></indexterm>The <filename>libpcp_trace</filename> Application Programming Interface (API) is called from C, C++, Fortran, and Java. Each language has access to the complete set of functionality offered by <filename>libpcp_trace</filename>. In some cases, the calling conventions differ slightly between languages. This section presents an overview of each of the different tracing mechanisms offered by the API, as well as an explanation of their mappings to the actual performance metrics exported by the trace PMDA.</para> +<section id="id5214320"> + +<title>Transactions </title> +<para><indexterm id="IG31340177504"><primary>pmtracebegin function</primary></indexterm> <indexterm id="IG31340177505"><primary>pmtracend function</primary></indexterm> <indexterm id="IG31340177506"><primary>transactions</primary></indexterm> <indexterm id="IG31340177507"><primary>pmtraceabort function</primary></indexterm>Paired calls to the <command>pmtracebegin</command> and <command>pmtraceend</command> API functions result in transaction data being sent to the trace PMDA with a measure of the time interval between the two calls. This interval is the transaction service time. Using the <command>pmtraceabort</command> call causes data for that particular transaction to be discarded. The trace PMDA exports transaction data through the following <literal>trace.transact</literal> metrics listed in <xref linkend="id5214410"/>:</para> +<table id="id5214410" frame="topbot"> + +<title><literal>trace.transact</literal> Metrics</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="174*"/> +<colspec colwidth="222*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Metric</para></entry><entry align="left" valign="bottom"><para>Description</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><literal><indexterm id="IG31340177508"><primary>trace.transact.ave_time metric</primary></indexterm> trace.transact.ave_time</literal></para></entry> +<entry align="left" valign="top"><para>The average service time per transaction type. This time is calculated over the last sample duration.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal><indexterm id="IG31340177509"><primary>trace.transact.count metric</primary></indexterm> trace.transact.count</literal></para></entry> +<entry align="left" valign="top"><para>The running count for each transaction type seen since the trace PMDA started.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal><indexterm id="IG31340177510"><primary>trace.transact.max_time metric</primary></indexterm> trace.transact.max_time</literal></para><para><literal/></para></entry> +<entry align="left" valign="top"><para>The maximum service time per transaction type within the last sample duration.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal><indexterm id="IG31340177511"><primary>trace.transact.min_time metric</primary></indexterm> trace.transact.min_time</literal></para></entry> +<entry align="left" valign="top"><para>The minimum service time per transaction type within the last sample duration.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal><indexterm id="IG31340177512"><primary>trace.transact.rate metric</primary></indexterm> trace.transact.rate</literal></para><para> </para></entry> +<entry align="left" valign="top"><para>The average rate at which each transaction type is completed. The rate is calculated over the last sample duration.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal><indexterm id="IG31340177513"><primary>trace.transact.total_time metric</primary></indexterm> trace.transact.total_time</literal></para></entry> +<entry align="left" valign="top"><para>The cumulative time spent processing each transaction since the trace PMDA started running.</para></entry></row></tbody></tgroup></table> +</section> +<section id="id5214714"> + +<title>Point Tracing </title> +<para><indexterm id="IG31340177514"><primary>point tracing</primary></indexterm> <indexterm id="IG31340177515"><primary>pmtracepoint function</primary></indexterm>Point tracing allows the application programmer to export metrics related to salient events. The <command>pmtracepoint</command> function is most useful when start and end points are not well defined. For example, this function is useful when the code branches in such a way that a transaction cannot be clearly identified, or when processing does not follow a transactional model, or when the desired instrumentation is akin to event rates rather than event service times. This data is exported through the <literal>trace.point</literal> metrics listed in <xref linkend="id5214762"/>:<table id="id5214762" frame="topbot"> + +<title><literal>trace.point</literal> Metrics</title> +<tgroup cols="2" colsep="0" rowsep="1"> +<colspec colwidth="149*"/> +<colspec colwidth="247*"/> +<thead> +<row valign="top"><entry align="left" valign="bottom"><para>Metric</para></entry><entry align="left" valign="bottom"><para>Description</para></entry></row></thead> +<tbody> +<row rowsep="0" valign="top"> +<entry align="left" valign="top"><para><literal>trace.point.count<indexterm id="IG31340177516"><primary>trace.point.count metric</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para>Running count of point observations for each tag seen since the trace PMDA started.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>trace.point.rate<indexterm id="IG31340177517"><primary>trace.point.rate metric</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para>The average rate at which observation points occur for each tag within the last sample duration.</para></entry></row></tbody></tgroup></table></para> +</section> +<section id="id5214931"> + +<title>Observations and Counters</title> +<para><indexterm id="IG31340177518"><primary>pmtraceobs function</primary></indexterm> <indexterm id="IG31340177519"><primary>pmtracepoint function</primary></indexterm> <indexterm id="IG31340177520"><primary>trace.observe metrics</primary></indexterm>The <command>pmtraceobs</command> and <command>pmtracecount</command> functions have similar semantics to <command>pmtracepoint</command>, but also allow an arbitrary numeric value to be passed to the trace PMDA. The most recent value for each tag is then immediately available from the PMDA. Observation data is exported through the <literal>trace.observe</literal> metrics listed in <xref linkend="id5215021"/>:</para> +<table id="id5215021" frame="topbot"> + +<title><literal>trace.observe</literal> Metrics</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="149*"/> +<colspec colwidth="247*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Metric</para></entry><entry align="left" valign="bottom"><para>Description</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><literal>trace.observe.count</literal></para></entry> +<entry align="left" valign="top"><para>Running count of observations seen since the trace PMDA started.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>trace.observe.rate</literal></para></entry> +<entry align="left" valign="top"><para>The average rate at which observations for each tag occur. This rate is calculated over the last sample duration.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>trace.observe.value</literal></para></entry> +<entry align="left" valign="top"><para>The numeric value associated with the observation last seen by the trace PMDA.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>trace.counter</literal></para></entry> +<entry align="left" valign="top"><para>Counter data is exported through the <literal>trace.counter</literal> metrics. The only difference between <literal>trace.counter</literal> and <literal>trace.observe</literal> metrics is that the numeric value of <literal>trace.counter</literal> must be a monotonic increasing count.</para></entry></row></tbody></tgroup></table> +</section> +<section id="id5215241"> + +<title>Configuring the Trace Library</title> +<para><indexterm id="IG31340177521"><primary>configuration</primary></indexterm><indexterm id="IG31340177522"><primary>environment variables</primary></indexterm> <indexterm id="IG31340177523"><primary>state flags</primary></indexterm> <indexterm id="IG31340177524"><primary>diagnostic output</primary></indexterm>The trace library is configurable through the use of environment variables listed in <xref linkend="id5215299"/> as well as through the state flags listed in <xref linkend="id5215745"/>. Both provide diagnostic output and enable or disable the configurable functionality within the library.</para> +<table id="id5215299" frame="topbot"> + +<title>Environment Variables</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="149*"/> +<colspec colwidth="247*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Name</para></entry><entry align="left" valign="bottom"><para>Description</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PCP_TRACE_HOST</literal><indexterm id="IG31340177525"><primary>PCP_TRACE_HOST variable</primary></indexterm></para></entry> +<entry align="left" valign="top"><para>The name of the host where the trace PMDA is running.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PCP_TRACE_PORT</literal><indexterm id="IG31340177526"><primary>PCP_TRACE_PORT variable</primary></indexterm></para></entry> +<entry align="left" valign="top"><para><indexterm id="IG31340177527"><primary>TCP/IP</primary></indexterm> TCP/IP port number on which the trace PMDA is accepting client connections.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PCP_TRACE_TIMEOUT</literal><indexterm id="IG31340177528"><primary>PCP_TRACE_TIMEOUT variable</primary></indexterm></para></entry> +<entry align="left" valign="top"><para>The number of seconds to wait until assuming that the initial connection is not going to be made, and timeout will occur. The default is three seconds.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PCP_TRACE_REQTIMEOUT</literal><indexterm id="IG31340177529"><primary>PCP_TRACE_REQTIMEOUT variable</primary></indexterm></para></entry> +<entry align="left" valign="top"><para><indexterm id="IG31340177530"><primary>asynchronous trace protocol</primary></indexterm> The number of seconds to allow before timing out on awaiting acknowledgment from the trace PMDA after trace data has been sent to it. This variable has no effect in the asynchronous trace protocol (refer to <xref linkend="id5215745"/>).</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PCP_TRACE_RECONNECT</literal><indexterm id="IG31340177531"><primary>PCP_TRACE_RECONNECT variable</primary></indexterm></para></entry> +<entry align="left" valign="top"><para>A list of values which represents the backoff approach that the <filename>libpcp_trace</filename> library routines take when attempting to reconnect to the trace PMDA after a connection has been lost. The list of values should be a positive number of seconds for the application to delay before making the next reconnection attempt. When the final value in the list is reached, that value is used for all subsequent reconnection attempts.</para></entry></row></tbody></tgroup></table> +<para><indexterm id="IG31340177532"><primary>state flags</primary></indexterm> <indexterm id="IG31340177533"><primary>flags</primary><secondary>state</secondary></indexterm> <indexterm id="IG31340177534"><primary>pmtracestate call</primary></indexterm> <indexterm id="IG31340177535"><primary>libpcp_trace library</primary><secondary id="Z980104750sdc">functions</secondary></indexterm>The <xref linkend="id5215745"/> are used to customize the operation of the <filename>libpcp_trace</filename> routines. These are registered through the <command>pmtracestate</command> call, and they can be set either individually or together.</para> +<table id="id5215745" frame="topbot"> + +<title>State Flags</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="170*"/> +<colspec colwidth="226*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Flag</para></entry><entry align="left" valign="bottom"><para>Description</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PMTRACE_STATE_NONE<indexterm id="IG31340177536"><primary>PMTRACE_STATE_NONE flag</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para><indexterm id="IG31340177537"><primary>synchronous protocol</primary></indexterm> The default. No state flags have been set, the fault-tolerant, synchronous protocol is used for communicating with the trace PMDA, and no diagnostic messages are displayed by the <filename/><filename>libpcp_trace</filename> routines.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PMTRACE_STATE_API<indexterm id="IG31340177538"><primary>PMTRACE_STATE_API flag</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para>High-level diagnostics. This flag simply displays entry into each of the API routines.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PMTRACE_STATE_COMMS<indexterm id="IG31340177539"><primary>PMTRACE_STATE_COMMS flag</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para>Diagnostic messages related to establishing and maintaining the communication channel between application and PMDA.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PMTRACE_STATE_PDU<indexterm id="IG31340177540"><primary>PMTRACE_STATE_PDU flag</primary></indexterm> <indexterm id="IG31340177541"><primary>PMTRACE_STATE_PDUBUF flag</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para><indexterm id="IG31340177542"><primary>PDU</primary></indexterm> The low-level details of the trace protocol data units (PDU) is displayed as each PDU is transmitted or received.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PMTRACE_STATE_PDUBUF<indexterm id="IG31340177543"><primary>PMTRACE_STATE_NOAGENT flag</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para>The full contents of the PDU buffers are dumped as PDUs are transmitted and received.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PMTRACE_STATE_NOAGENT<indexterm id="IG31340177544"><primary>PMTRACE_STATE_NOAGENT flag</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para><indexterm id="IG31340177545"><primary>interprocess communication</primary><secondary>PMTRACE_STATE_NOAGENT flag</secondary></indexterm> <indexterm id="IG31340177546"><primary>debugging and testing</primary></indexterm> Interprocess communication control. If this flag is set, it causes interprocess communication between the instrumented application and the trace PMDA to be skipped. This flag is a debugging aid for applications using <filename>libpcp_trace</filename>.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><literal>PMTRACE_STATE_ASYNC<indexterm id="IG31340177547"><primary>PMTRACE_STATE_ASYNC flag</primary></indexterm></literal></para></entry> +<entry align="left" valign="top"><para><indexterm id="IG31340177548"><primary>asynchronous trace protocol</primary></indexterm> <indexterm id="IG31340177549"><primary>libpcp_trace library</primary><secondary>entry points</secondary></indexterm> Asynchronous trace protocol. This flag enables the asynchronous trace protocol so that the application does not block awaiting acknowledgment PDUs from the trace PMDA. In order for the flag to be effective, it must be set before using the other <filename/><filename>libpcp_trace</filename> entry points.</para></entry></row></tbody></tgroup></table> +</section> +</section> + + + + + + + + +</chapter> + + +<appendix id="LE54271-PARENT"> + +<title>Acronyms</title> +<para><xref linkend="id5216717"/> provides a glossary of the acronyms used in the Performance Co-Pilot (PCP) documentation, help cards, man pages, and user interface.<indexterm id="IG31340177566"><primary>glossary</primary></indexterm><indexterm id="IG31340177567"><primary>acronyms</primary></indexterm></para> +<table id="id5216717" frame="topbot"> + +<title>Performance Co-Pilot Acronyms and Their Meanings</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="92*"/> +<colspec colwidth="304*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Acronym</para></entry><entry align="left" valign="bottom"><para>Meaning</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para>API</para></entry> +<entry align="left" valign="top"><para>Application Programming Interface</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>DBMS</para></entry> +<entry align="left" valign="top"><para>Database Management System</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177568"><primary>DNS</primary></indexterm> DNS</para></entry> +<entry align="left" valign="top"><para>Domain Name Service</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177569"><primary>DSO</primary></indexterm> DSO</para></entry> +<entry align="left" valign="top"><para>Dynamic Shared Object</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>I/O</para></entry> +<entry align="left" valign="top"><para>Input/Output</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>IPC</para></entry> +<entry align="left" valign="top"><para>Interprocess Communication</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177570"><primary>PCP</primary><secondary>acronym</secondary></indexterm> PCP</para></entry> +<entry align="left" valign="top"><para>Performance Co-Pilot</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177571"><primary>PDU</primary></indexterm> PDU</para></entry> +<entry align="left" valign="top"><para>Protocol data unit</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177572"><primary>PMAPI</primary><secondary>acronym</secondary></indexterm> PMAPI</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Application Programming Interface</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177573"><primary>PMCD</primary><secondary>acronym</secondary></indexterm> PMCD</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Collection Daemon</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177575"><primary>PMDA</primary><secondary>acronym</secondary></indexterm> PMDA</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Domain Agent</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177576"><primary>PMID</primary><secondary>acronym</secondary></indexterm> PMID</para></entry> +<entry align="left" valign="top"><para>Performance Metric Identifier</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177577"><primary>PMNS</primary><secondary>acronym</secondary></indexterm> PMNS</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Name Space</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31340177578"><primary>TCP/IP</primary></indexterm> TCP/IP</para></entry> +<entry align="left" valign="top"><para>Transmission Control Protocol/Internet Protocol</para></entry></row></tbody></tgroup></table> +</appendix> +<index id="sgi-index"> + +<indexentry> + <primaryie>__pmID_int structure <link linkend="IG31340177121">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>__pmInDom_int structure <link linkend="IG31340177141">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>access controls <link linkend="IG31340177495">Configuring the Trace PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>acronyms <link linkend="IG31340177567">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>ancillary support services <link linkend="IG31340177417">PMAPI Ancillary Support Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Application Programming Interface <link linkend="IG31340177257">PMAPI--The Performance Metrics API</link> <link linkend="IG31340177502nat">Memory Mapped Values API</link> <link linkend="IG31340177502">Trace API</link> <link linkend="IG31340177472">Application Interaction</link> <link linkend="IG31340177502">Trace API</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>application developers<link linkend="IG31340177554">Instrumenting Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>application programs <link linkend="ITch01-114">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>applications</primaryie> + <secondaryie>compiling <link linkend="IG31340177460">Compiling and Linking PMAPI Applications</link></secondaryie> + <secondaryie>instrumentation <link linkend="IG31340177550">Application and PCP Relationship</link></secondaryie> + <secondaryie>interaction <link linkend="IG31340177471">Application Interaction</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>architecture <link linkend="IG313401778">PCP Architecture</link> <link linkend="IG3134017777">PMDA Architecture</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>archive logs</primaryie> + <secondaryie>context services <link linkend="IG31340177347">PMAPI Context Services</link></secondaryie> + <secondaryie>performance data <link linkend="IG31340177258">PMAPI--The Performance Metrics API</link> <link linkend="IG31340177266">Current PMAPI Context</link></secondaryie> + <secondaryie>performance management <link linkend="IG31340177562">Application and PCP Relationship</link></secondaryie> + <secondaryie>pmGetArchiveEnd function <link linkend="IG31340177402"><command>pmGetArchiveEnd</command> Function</link></secondaryie> + <secondaryie>pmGetInDomArchive function <link linkend="IG31340177405"><command>pmGetInDomArchive</command> Function</link></secondaryie> + <secondaryie>retrospective sources <link linkend="IG3134017731">Retrospective Sources of Performance Metrics</link></secondaryie> + <secondaryie>time control services <link linkend="IG31340177415">PMAPI Time Control Services</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>archive-specific services <link linkend="IG31340177401"><command>pmGetArchiveLabel</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Cluster PMDA <link linkend="IG3134017717">Distributed Collection</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>arrays</primaryie> + <secondaryie>instance description <link linkend="IG31340177140">Data Structures</link></secondaryie> + <secondaryie>N dimensional data <link linkend="IG31340177134">N Dimensional Data</link></secondaryie> + <secondaryie>performance metrics <link linkend="IG31340177278">Performance Metrics Values</link> <link linkend="IG31340177283">Variable Length Argument and Results Lists</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>asynchronous trace protocol <link linkend="IG31340177530">Configuring the Trace Library</link> <link linkend="IG31340177548">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>audience <link linkend="IG313401772">Programming Performance Co-Pilot</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>automated alarms <link linkend="IG31340177563">Application and PCP Relationship</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>caching PMDA <link linkend="IG31340177106">Caching PMDA</link> <link linkend="IG31340177153">Latency and Threads of Control</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>chkhelp tool <link linkend="IG3134017735">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Cisco PMDA <link linkend="IG3134017716">Distributed Collection</link> <link linkend="IG31340177107">Caching PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>client development <link linkend="IG3134017752">Client Development and PMAPI</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>clusters <link linkend="IG3134017725">Name Space</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>collection time <link linkend="IG31340177267">Current PMAPI Context</link> <link linkend="IG31340177352"><command>pmNewContext</command> Function</link> <link linkend="IG31340177357"><command>pmWhichContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>collection tools <link linkend="IG3134017712">PCP Architecture</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>collector hosts <link linkend="IG3134017719">Distributed Collection</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>COLOR_INDOM <link linkend="IG31340177143">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>compiling and linking <link linkend="IG31340177461">Compiling and Linking PMAPI Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>component software <link linkend="IG3134017733">Overview of Component Software</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>computation state <link linkend="IG31340177556">Instrumenting Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>configuration <link linkend="IG31340177521">Configuring the Trace Library</link> <link linkend="IG31340177251">Configuring PCP Tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>context services <link linkend="IG31340177320">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>control threads <link linkend="IG31340177150">Latency and Threads of Control</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>counter semantics <link linkend="IG31340177131">Semantics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>customization <link linkend="IG313401777">Programming Performance Co-Pilot</link> <link linkend="IG31340177565">Instrumenting Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>daemon process method <link linkend="IG3134017750">Daemon Process Method</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>data export <link linkend="IG31340177552">Application and PCP Relationship</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>data structures <link linkend="IG31340177118">Data Structures</link> <link linkend="IG31340177137">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>dbpmda man page <link linkend="IG3134017768">Implementing a PMDA</link> <link linkend="IG31340177229">Overview</link> <link linkend="IG31340177236"><command>dbpmda</command> Debug Utility</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>dbx man page <link linkend="IG31340177228">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>debugging and testing <link linkend="IG31340177227">Testing and Debugging a PMDA</link> <link linkend="IG31340177546">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>debugging flags</primaryie> + <seeie>flags</seeie> +</indexentry> + +<indexentry> + <primaryie>delays <link linkend="IG31340177151">Latency and Threads of Control</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>design requirements <link linkend="IG3134017761">Implementing a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>diagnostic output <link linkend="IG31340177524">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>dimensionality and scale <link linkend="IG31340177272">Performance Metric Descriptions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>discrete semantics <link linkend="IG31340177133">Semantics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>distributed performance management</primaryie> + <secondaryie>data transportation <link linkend="IG31340177561">Application and PCP Relationship</link></secondaryie> + <secondaryie>metrics collection <link linkend="IG3134017715">Distributed Collection</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>dlopen man page <link linkend="IG3134017746">In-Process (DSO) Method</link> <link linkend="IG3134017796">DSO PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>DNS <link linkend="IG31340177568">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>domains</primaryie> + <secondaryie>definition <link linkend="IG31340177110">Overview</link></secondaryie> + <secondaryie>fields <link linkend="IG3134017727">Name Space</link></secondaryie> + <secondaryie>numbers <link linkend="IG31340177113">Domains</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>dometric function <link linkend="IG31340177302"><command>pmTraversePMNS</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>DSO <link linkend="IG31340177569">Acronyms</link></primaryie> + <secondaryie>architecture <link linkend="IG3134017779">PMDA Architecture</link></secondaryie> + <secondaryie>disadvantages <link linkend="IG31340177100">Daemon PMDA</link></secondaryie> + <secondaryie>implementation <link linkend="IG3134017795">DSO PMDA</link></secondaryie> + <secondaryie>interface <link linkend="IG31340177178">PMDA Interface</link></secondaryie> + <secondaryie>PMDA building <link linkend="IG3134017745">In-Process (DSO) Method</link></secondaryie> + <secondaryie>PMDA initialization <link linkend="IG31340177209">Common Initialization</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>dynamic shared object</primaryie> + <seeie>DSO</seeie> +</indexentry> + +<indexentry> + <primaryie>embedded calls <link linkend="IG31340177555">Instrumenting Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>environment variables <link linkend="IG31340177522">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>error handling <link linkend="IG31340177458">Handling PMAPI Errors</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>examples</primaryie> + <secondaryie>alarm tools <link linkend="IG3134017775">Implementing a PMDA</link></secondaryie> + <secondaryie>Install script <link linkend="IG31340177243">Installing a PMDA</link></secondaryie> + <secondaryie>MMV PMDA <link linkend="IG31340177465nat">Instrumenting Applications</link></secondaryie> + <secondaryie>programming issues <link linkend="IG31340177445">PMAPI Programming Issues and Examples</link></secondaryie> + <secondaryie>Remove script <link linkend="IG31340177249">Removing a PMDA</link></secondaryie> + <secondaryie>rolling-window sampling <link linkend="IG31340177493">Rolling-Window Periodic Sampling Example</link></secondaryie> + <secondaryie>simple and trivial PMDAs <link linkend="IG31340177109">Domains, Metrics, and Instances</link></secondaryie> + <secondaryie>time control functions <link linkend="IG31340177416">PMAPI Time Control Services</link></secondaryie> + <secondaryie>trace PMDA <link linkend="IG31340177465">Instrumenting Applications</link></secondaryie> + <secondaryie>visualization tools <link linkend="IG3134017774">Implementing a PMDA</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>execv system call <link linkend="IG31340177102">Daemon PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>exporting data <link linkend="IG31340177147">Extracting the Information</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>flags</primaryie> + <secondaryie>debugging <link linkend="IG31340177233">Debugging Information</link></secondaryie> + <secondaryie>state <link linkend="IG31340177533">Configuring the Trace Library</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>fork system call <link linkend="IG31340177101">Daemon PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>glossary <link linkend="IG31340177566">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>handle context <link linkend="IG31340177375"><command>pmReconnectContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>help text</primaryie> + <secondaryie>creation <link linkend="IG31340177241">Installing a PMDA</link></secondaryie> + <secondaryie>initialization <link linkend="IG31340177210">Common Initialization</link></secondaryie> + <secondaryie>location <link linkend="IG31340177239">Installing a PMDA</link></secondaryie> + <secondaryie>PDU_TEXT_REQ <link linkend="IG3134017792">Overview</link></secondaryie> + <secondaryie>pmLookupInDomText function <link linkend="IG31340177311"><command>pmLookupInDomText</command> Function</link></secondaryie> + <secondaryie>pmLookupText function <link linkend="IG31340177169">Management of Evolution within a PMDA</link> <link linkend="IG31340177313"><command>pmLookupText</command> Function</link></secondaryie> + <secondaryie>structure specification <link linkend="IG3134017767">Implementing a PMDA</link></secondaryie> + <secondaryie>terse and extended descriptions <link linkend="IG31340177158">PMDA Help Text</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>historical buffers <link linkend="IG31340177487">Simple Periodic Sampling</link> <link linkend="IG31340177492">Rolling-Window Periodic Sampling</link> <link linkend="IG31340177497">Configuring the Trace PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>identification tags <link linkend="IG31340177473">Application Interaction</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>implementation <link linkend="IG3134017760">Implementing a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>indom instance domain <link linkend="IG31340177309"><command>pmLookupInDomText</command> Function</link> <link linkend="IG31340177359"><command>pmAddProfile</command> Function</link> <link linkend="IG31340177406"><command>pmGetInDomArchive</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>information extraction <link linkend="IG31340177146">Extracting the Information</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>initialization <link linkend="IG31340177451">Initializing New Metrics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>instance domain refresh <link linkend="IG31340177500">Configuring the Trace PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>instance domain services <link linkend="IG31340177314"><command>pmGetInDom</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>instantaneous semantics <link linkend="IG31340177132">Semantics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>instlist argument <link linkend="IG31340177315"><command>pmGetInDom</command> Function</link> <link linkend="IG31340177360"><command>pmAddProfile</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>instrumentation <link linkend="IG31340177468nat">Performance Instrumentation and Sampling</link> <link linkend="IG31340177468">Performance Instrumentation and Tracing</link> <link linkend="IG31340177551">Application and PCP Relationship</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>integrating a PMDA <link linkend="IG31340177238">Integration of a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>internal instance identifier <link linkend="IG31340177277">Performance Metrics Values</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>interpolated metrics <link linkend="IG31340177372"><command>pmSetMode</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>interprocess communication</primaryie> + <seeie>IPC</seeie> + <secondaryie>PMTRACE_STATE_NOAGENT flag <link linkend="IG31340177545">Configuring the Trace Library</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>IPC</primaryie> + <secondaryie>DSO <link linkend="IG3134017749">In-Process (DSO) Method</link></secondaryie> + <secondaryie>PMDA <link linkend="IG3134017765">Implementing a PMDA</link></secondaryie> + <secondaryie>trace API <link linkend="IG31340177474">Application Interaction</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>item numbers <link linkend="IG3134017726">Name Space</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>iterative processing <link linkend="IG31340177454">Iterative Processing of Values</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>latency <link linkend="IG31340177149">Latency and Threads of Control</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>leaf node <link linkend="IG31340177303"><command>pmTraversePMNS</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>libpcp_mmv library</primaryie> + <secondaryie>Application Programming Interface <link linkend="IG31340177503nat">Memory Mapped Values API</link></secondaryie> + <secondaryie>instrumenting applications <link linkend="IG31340177464nat">Instrumenting Applications</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>libpcp_trace library</primaryie> + <secondaryie>Application Programming Interface <link linkend="IG31340177503">Trace API</link></secondaryie> + <secondaryie>entry points <link linkend="IG31340177549">Configuring the Trace Library</link></secondaryie> + <secondaryie>functions <link linkend="IG31340177535">Configuring the Trace Library</link></secondaryie> + <secondaryie>instrumenting applications <link linkend="IG31340177464">Instrumenting Applications</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>library reentrancy <link linkend="IG3134017758">Library Reentrancy and Threaded Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>metric description services <link linkend="IG31340177306"><command>pmLookupDesc</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>metrics</primaryie> + <secondaryie>API <link linkend="IG31340177260">Naming and Identifying Performance Metrics</link></secondaryie> + <secondaryie>definition <link linkend="IG31340177111">Overview</link> <link linkend="IG31340177114">Metrics</link></secondaryie> + <secondaryie>name and value <link linkend="IG31340177447">Symbolic Association between a Metric's Name and Value</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>metrics and instances <link linkend="IG31340177112">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>metrics description services <link linkend="IG31340177305"><command>pmLookupDesc</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>metrics services <link linkend="IG31340177384"><command>pmFetch</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>mmv_lookup_value_desc function <link linkend="Z1033577633nat">Getting a Handle on Mapped Values</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>mmv_stats_init function <link linkend="IG31340177504nat">Starting and Stopping Instrumentation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>mmv_stats_stop function <link linkend="IG31340177505nat">Starting and Stopping Instrumentation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>mmv_stats_inc function <link linkend="Z1033577634nat">Updating Mapped Values</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>mmv_stats_interval_start function <link linkend="Z1033577635nat">Elapsed Time Measures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>mmv_stats_interval_end function <link linkend="Z1033577636nat">Elapsed Time Measures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>monitoring tools <link linkend="IG3134017711">PCP Architecture</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>multidimensional arrays <link linkend="IG31340177136">N Dimensional Data</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>multiple threads <link linkend="IG3134017757">Library Reentrancy and Threaded Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>MMV PMDA</primaryie> + <secondaryie>description <link linkend="IG31340177462nat">Instrumenting Applications</link></secondaryie> + <secondaryie>design <link linkend="IG31340177470nat">MMV PMDA Design</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>name space <link linkend="IG3134017722">Name Space</link> <link linkend="IG31340177155">Name Space</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>new metrics <link linkend="IG31340177160">Management of Evolution within a PMDA</link> <link linkend="IG31340177452">Initializing New Metrics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>new PMDA <link linkend="IG31340177244">Upgrading a PMNS to Include Metrics from a New PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>newhelp man page <link linkend="IG31340177159">PMDA Help Text</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>newhelp tool <link linkend="IG3134017737">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>NOW_INDOM <link linkend="IG31340177144">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>observation metric units <link linkend="IG31340177498">Configuring the Trace PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>parallelism <link linkend="IG31340177557">Instrumenting Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCP</primaryie> + <secondaryie>acronym <link linkend="IG31340177570">Acronyms</link></secondaryie> + <secondaryie>description <link linkend="IG313401770">Programming Performance Co-Pilot</link></secondaryie> + <secondaryie>tool summaries <link linkend="IG3134017734">Application and Agent Development</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>PCP_TRACE_HOST variable <link linkend="IG31340177525">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCP_TRACE_PORT variable <link linkend="IG31340177526">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCP_TRACE_RECONNECT variable <link linkend="IG31340177531">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCP_TRACE_REQTIMEOUT variable <link linkend="IG31340177529">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCP_TRACE_TIMEOUT variable <link linkend="IG31340177528">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU <link linkend="IG3134017780">Overview</link> <link linkend="IG31340177475">Application Interaction</link> <link linkend="IG31340177542">Configuring the Trace Library</link> <link linkend="IG31340177571">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_AUTH <link linkend="IG3134017791nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_DESC_REQ <link linkend="IG3134017789">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_FETCH <link linkend="IG3134017783">Overview</link> <link linkend="IG31340177219">Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_INSTANCE_REQ <link linkend="IG3134017787">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_PMNS_CHILD <link linkend="IG3134017785nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_PMNS_NAMES <link linkend="IG3134017783nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_PMNS_TRAVERSE <link linkend="IG3134017787nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_PMNS_IDS <link linkend="IG3134017789nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_PROFILE <link linkend="IG3134017785">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_RESULT <link linkend="IG3134017794">Overview</link> <link linkend="IG31340177218">Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU_TEXT_REQ <link linkend="IG3134017791">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>performance instrumentation <link linkend="IG313401775">Programming Performance Co-Pilot</link> <link linkend="IG31340177467nat">Performance Instrumentation and Sampling</link> <link linkend="IG31340177467">Performance Instrumentation and Tracing</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Performance Metric Identifier</primaryie> + <seeie>PMID</seeie> +</indexentry> + +<indexentry> + <primaryie>performance metrics</primaryie> + <seeie>metrics</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Application Programming Interface</primaryie> + <seeie>PMAPI</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Collection Daemon</primaryie> + <seeie>PMCD</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Domain Agent</primaryie> + <seeie>PMDA</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Name Space</primaryie> + <seeie>PMNS</seeie> +</indexentry> + +<indexentry> + <primaryie>periodic sampling <link linkend="IG31340177485">Simple Periodic Sampling</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pipe <link linkend="IG31340177103">Daemon PMDA</link> <link linkend="IG31340177104">Daemon PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_CONTEXT_ARCHIVE type <link linkend="IG31340177348"><command>pmNewContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_CONTEXT_HOST type <link linkend="IG31340177349"><command>pmNewContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_ERR_CONV error code <link linkend="IG31340177177">Management of Evolution within a PMDA</link> <link linkend="IG31340177422"><command>pmExtractValue</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_ERR_INST error code <link linkend="IG31340177197"><literal>simple_store</literal> in the Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_ERR_PMID error code <link linkend="IG31340177167">Management of Evolution within a PMDA</link> <link linkend="IG31340177198"><literal>simple_store</literal> in the Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_ERR_SIGN error code <link linkend="IG31340177424"><command>pmExtractValue</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_ERR_TIMEOUT error code <link linkend="IG31340177388"><command>pmFetch</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_ERR_TRUNC error code <link linkend="IG31340177423"><command>pmExtractValue</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_IN_NULL instance identifier <link linkend="IG31340177264">Performance Metric Instances</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_INDOM_NULL instance domain</primaryie> + <secondaryie>data structures <link linkend="IG31340177125">Data Structures</link> <link linkend="IG31340177145">Data Structures</link></secondaryie> + <secondaryie>description <link linkend="IG31340177263">Performance Metric Instances</link></secondaryie> + <secondaryie>pmAddProfile function <link linkend="IG31340177362"><command>pmAddProfile</command> Function</link></secondaryie> + <secondaryie>pmDelProfile function <link linkend="IG31340177363"><command>pmDelProfile</command> Function</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>PM_SEM_COUNTER semantic type <link linkend="IG31340177128">Semantics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_SEM_DISCRETE semantic type <link linkend="IG31340177130">Semantics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_SEM_INSTANT semantic type <link linkend="IG31340177126">Data Structures</link> <link linkend="IG31340177129">Semantics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_TYPE_AGGREGATE type <link linkend="IG31340177270">Performance Metric Descriptions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_TYPE_NOSUPPORT value <link linkend="IG31340177165">Management of Evolution within a PMDA</link> <link linkend="IG31340177271">Performance Metric Descriptions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_TYPE_STRING type <link linkend="IG31340177269">Performance Metric Descriptions</link> <link linkend="IG31340177425"><command>pmExtractValue</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_TYPE_EVENT type <link linkend="IG31340177269nat">Performance Metric Descriptions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_VAL_INSITU value <link linkend="IG31340177279">Performance Metrics Values</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmAddProfile function <link linkend="IG3134017784">Overview</link> <link linkend="IG31340177322">PMAPI Context Services</link> <link linkend="IG31340177361"><command>pmAddProfile</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMAPI <link linkend="IG3134017739">Application and Agent Development</link> <link linkend="IG31340177262">Performance Metric Instances</link></primaryie> + <seealsoie>metrics</seealsoie> + <secondaryie>acronym <link linkend="IG31340177572">Acronyms</link></secondaryie> + <secondaryie>ancillary support services <link linkend="IG31340177418">PMAPI Ancillary Support Services</link></secondaryie> + <secondaryie>application compiling <link linkend="IG31340177459">Compiling and Linking PMAPI Applications</link></secondaryie> + <secondaryie>archive-specific services <link linkend="IG31340177400"><command>pmGetArchiveLabel</command> Function</link></secondaryie> + <secondaryie>client development <link linkend="IG3134017755">Client Development and PMAPI</link></secondaryie> + <secondaryie>context services <link linkend="IG31340177321">PMAPI Context Services</link></secondaryie> + <secondaryie>current context <link linkend="IG31340177265">Current PMAPI Context</link></secondaryie> + <secondaryie>description <link linkend="IG31340177256">PMAPI--The Performance Metrics API</link></secondaryie> + <secondaryie>description services <link linkend="IG31340177308"><command>pmLookupDesc</command> Function</link></secondaryie> + <secondaryie>error handling <link linkend="IG31340177291">PMAPI Error Handling</link> <link linkend="IG31340177457">Handling PMAPI Errors</link></secondaryie> + <secondaryie>identifying metrics <link linkend="IG31340177261">Naming and Identifying Performance Metrics</link></secondaryie> + <secondaryie>initializing new metrics <link linkend="IG31340177450">Initializing New Metrics</link></secondaryie> + <secondaryie>instance domain services <link linkend="IG31340177317"><command>pmGetInDom</command> Function</link></secondaryie> + <secondaryie>introduction <link linkend="IG313401774">Programming Performance Co-Pilot</link></secondaryie> + <secondaryie>iterative processing <link linkend="IG31340177453">Iterative Processing of Values</link></secondaryie> + <secondaryie>man page <link linkend="IG3134017721">Distributed Collection</link></secondaryie> + <secondaryie>metrics services <link linkend="IG31340177383"><command>pmFetch</command> Function</link></secondaryie> + <secondaryie>Name Space services <link linkend="IG31340177292"><command>pmGetChildren</command> Function</link></secondaryie> + <secondaryie>program evolution <link linkend="IG31340177455">Accommodating Program Evolution</link></secondaryie> + <secondaryie>programming issues <link linkend="IG31340177443">PMAPI Programming Issues and Examples</link> <link linkend="IG31340177444">PMAPI Programming Issues and Examples</link></secondaryie> + <secondaryie>programming style <link linkend="IG31340177281">PMAPI Programming Style and Interaction</link></secondaryie> + <secondaryie>record-mode services <link linkend="IG31340177395"><command>pmRecordAddHost</command> Function</link></secondaryie> + <secondaryie>time control services <link linkend="IG31340177413">PMAPI Time Control Services</link></secondaryie> + <secondaryie>timezone services <link linkend="IG31340177377"><command>pmNewContextZone</command> Function</link></secondaryie> + <secondaryie>variable length arguments <link linkend="IG31340177282">Variable Length Argument and Results Lists</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmAtomStr function <link linkend="IG31340177174">Management of Evolution within a PMDA</link> <link linkend="IG31340177433"><command>pmAtomStr</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmAtomValue structure <link linkend="IG31340177190">Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMCD</primaryie> + <secondaryie>acronym <link linkend="IG31340177573">Acronyms</link></secondaryie> + <secondaryie>distributed collection <link linkend="IG3134017718">Distributed Collection</link></secondaryie> + <secondaryie>overview <link linkend="IG3134017713">PCP Architecture</link></secondaryie> + <secondaryie>pmReconnectContext function <link linkend="IG31340177373"><command>pmReconnectContext</command> Function</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>PMCD_RECONNECT_TIMEOUT variable <link linkend="IG31340177376"><command>pmReconnectContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMCD_REQUEST_TIMOUT variable <link linkend="IG31340177389"><command>pmFetch</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmchart command <link linkend="IG313401779">PCP Architecture</link> <link linkend="IG3134017769">Implementing a PMDA</link> <link linkend="IG31340177499">Configuring the Trace PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmclient tool <link linkend="IG3134017741">Application and Agent Development</link></primaryie> + <secondaryie>brief description <link linkend="IG3134017738">Application and Agent Development</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmConvScale function <link linkend="IG31340177173">Management of Evolution within a PMDA</link> <link linkend="IG31340177426"><command>pmConvScale</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMDA</primaryie> + <secondaryie>acronym <link linkend="IG31340177575">Acronyms</link></secondaryie> + <secondaryie>architecture <link linkend="IG3134017778">PMDA Architecture</link></secondaryie> + <secondaryie>checklist <link linkend="IG3134017766">Implementing a PMDA</link></secondaryie> + <secondaryie>development <link linkend="IG3134017744">PMDA Development</link></secondaryie> + <secondaryie>evolution <link linkend="IG31340177161">Management of Evolution within a PMDA</link></secondaryie> + <secondaryie>help text <link linkend="IG31340177157">PMDA Help Text</link></secondaryie> + <secondaryie>initialization <link linkend="IG31340177207">Initializing a PMDA</link></secondaryie> + <secondaryie>Install script <link linkend="IG31340177240">Installing a PMDA</link> <link linkend="IG31340177246">Upgrading a PMNS to Include Metrics from a New PMDA</link></secondaryie> + <secondaryie>integration <link linkend="IG31340177237">Integration of a PMDA</link></secondaryie> + <secondaryie>interface <link linkend="IG31340177178">PMDA Interface</link></secondaryie> + <secondaryie>introduction <link linkend="IG313401773">Programming Performance Co-Pilot</link></secondaryie> + <secondaryie>man page <link linkend="IG3134017720">Distributed Collection</link></secondaryie> + <secondaryie>removal <link linkend="IG31340177247">Removing a PMDA</link></secondaryie> + <secondaryie>structures <link linkend="IG31340177199">PMDA Structures</link></secondaryie> + <secondaryie>trace <link linkend="IG31340177463">Instrumenting Applications</link></secondaryie> + <secondaryie>writing <link linkend="IG3134017759">Writing a PMDA</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmda library <link linkend="IG3134017742">Application and Agent Development</link></primaryie> + <seeie>PMDA</seeie> +</indexentry> + +<indexentry> + <primaryie>mmv library <link linkend="IG3134017742nat">Application and Agent Development</link></primaryie> + <seeie>MMV</seeie> +</indexentry> + +<indexentry> + <primaryie>PMDA_PMID macro <link linkend="IG31340177122">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaAttribute callback <link linkend="IG31340180nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaChildren callback <link linkend="IG31340179nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdacisco man page <link linkend="IG31340177108">Caching PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaConnect man page <link linkend="IG31340177202">PMDA Structures</link> <link linkend="IG31340177223">Daemon Initialization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaDaemon man page <link linkend="IG31340177204">PMDA Structures</link> <link linkend="IG31340177220">Daemon Initialization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaDesc callback <link linkend="IG31340177182">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaDSO man page <link linkend="IG31340177203">PMDA Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaExt structure <link linkend="IG31340177185">Overview</link> <link linkend="IG31340177201">PMDA Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaFetch callback <link linkend="IG31340177179">Overview</link> <link linkend="IG31340177214">Trivial PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaGetOptions man page <link linkend="IG31340177205">PMDA Structures</link> <link linkend="IG31340177221">Daemon Initialization</link> <link linkend="IG31340177225">Daemon Initialization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaIndom structure <link linkend="IG31340177139">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaInit man page <link linkend="IG31340177142">Data Structures</link> <link linkend="IG31340177206">PMDA Structures</link> <link linkend="IG31340177211">Common Initialization</link> <link linkend="IG31340177212">Common Initialization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaInstance callback <link linkend="IG31340177181">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaInstid structure <link linkend="IG31340177138">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaInterface structure <link linkend="IG31340177200">PMDA Structures</link> <link linkend="IG31340177208">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaMain man page <link linkend="IG31340177224">Daemon Initialization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaMetric structure <link linkend="IG31340177123">Data Structures</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaName callback <link linkend="IG31340178nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaOpenLog man page <link linkend="IG31340177222">Daemon Initialization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaPMID callback <link linkend="IG31340177nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaProfile callback <link linkend="IG31340177180">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaStore callback <link linkend="IG31340177184">Overview</link> <link linkend="IG31340177196"><literal>simple_store</literal> in the Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaText callback <link linkend="IG31340177183">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdatrace man page <link linkend="IG31340177466">Performance Instrumentation and Tracing</link> <link linkend="IG31340177469">Performance Instrumentation and Tracing</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdbg man page <link linkend="IG31340177230">Overview</link> <link linkend="IG31340177231">Debugging Information</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmDelProfile function <link linkend="IG31340177323">PMAPI Context Services</link> <link linkend="IG31340177364"><command>pmDelProfile</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmDesc structure <link linkend="IG31340177119">Data Structures</link> <link linkend="IG31340177164">Management of Evolution within a PMDA</link> <link linkend="IG31340177268">Performance Metric Descriptions</link> <link linkend="IG31340177274">Performance Metric Descriptions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmDestroyContext function <link linkend="IG31340177354"><command>pmDestroyContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmDupContext function <link linkend="IG31340177324">PMAPI Context Services</link> <link linkend="IG31340177355"><command>pmDupContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmErrStr function <link linkend="IG31340177419"><command>pmErrStr</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmExtractValue function <link linkend="IG31340177172">Management of Evolution within a PMDA</link> <link linkend="IG31340177420"><command>pmExtractValue</command> Function</link> <link linkend="IG31340177428"><command>pmConvScale</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmFetch function <link linkend="IG31340177275">Performance Metrics Values</link> <link linkend="IG31340177280">Performance Metrics Values</link> <link linkend="IG31340177289">Variable Length Argument and Results Lists</link> <link linkend="IG31340177325">PMAPI Context Services</link> <link linkend="IG31340177351"><command>pmNewContext</command> Function</link> <link linkend="IG31340177370"><command>pmSetMode</command> Function</link> <link linkend="IG31340177385"><command>pmFetch</command> Function</link> <link linkend="IG31340177387"><command>pmFetch</command> Function</link> <link linkend="IG31340177390"><command>pmFreeResult</command> Function</link> <link linkend="IG31340177411"><command>pmFetchArchive</command> Function</link> <link linkend="IG31340177435"><command>pmPrintValue</command> Function</link> <link linkend="IG31340177440"><command>pmSortInstances</command> Function</link> <link linkend="IG31340177449">Symbolic Association between a Metric's Name and Value</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmFetch man page <link linkend="IG3134017782">Overview</link> <link linkend="IG31340177166">Management of Evolution within a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmFetchArchive function <link linkend="IG31340177326">PMAPI Context Services</link> <link linkend="IG31340177369"><command>pmSetMode</command> Function</link> <link linkend="IG31340177412"><command>pmFetchArchive</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmflush function <link linkend="IG31340177437"><command>pmflush</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmFreeResult function <link linkend="IG31340177290">Variable Length Argument and Results Lists</link> <link linkend="IG31340177386"><command>pmFetch</command> Function</link> <link linkend="IG31340177391"><command>pmFreeResult</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmgadgets command <link linkend="IG3134017770">Implementing a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmgenmap tool <link linkend="IG3134017743">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetArchiveEnd function <link linkend="IG31340177327">PMAPI Context Services</link> <link linkend="IG31340177403"><command>pmGetArchiveEnd</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetArchiveLabel function <link linkend="IG31340177328">PMAPI Context Services</link> <link linkend="IG31340177399"><command>pmGetArchiveLabel</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetChildren function <link linkend="IG3134017785nat">Overview</link> <link linkend="IG31340177288">Variable Length Argument and Results Lists</link> <link linkend="IG31340177293"><command>pmGetChildren</command> Function</link> <link linkend="IG31340177294"><command>pmGetChildrenStatus</command> Function</link> <link linkend="IG31340177329">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetChildrenStatus function <link linkend="IG31340177330">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetContextHostName function <link linkend="IG31340177330nat">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetInDom function <link linkend="IG3134017786">Overview</link> <link linkend="IG31340177286">Variable Length Argument and Results Lists</link> <link linkend="IG31340177316"><command>pmGetInDom</command> Function</link> <link linkend="IG31340177332">PMAPI Context Services</link> <link linkend="IG31340177367"><command>pmSetMode</command> Function</link> <link linkend="IG31340177408"><command>pmGetInDomArchive</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetInDomArchive function <link linkend="IG31340177333">PMAPI Context Services</link> <link linkend="IG31340177407"><command>pmGetInDomArchive</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetPMNSLocation function <link linkend="IG31340177295"><command>pmGetPMNSLocation</command> Function</link> <link linkend="IG31340177331">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMID</primaryie> + <secondaryie>acronym <link linkend="IG31340177576">Acronyms</link></secondaryie> + <secondaryie>introduction <link linkend="IG3134017724">Name Space</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmIDStr function <link linkend="IG31340177430"><command>pmIDStr</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmie command <link linkend="IG3134017772">Implementing a PMDA</link> <link linkend="IG31340177252">Configuring PCP Tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmieconf command <link linkend="IG3134017773">Implementing a PMDA</link> <link linkend="IG31340177253">Configuring PCP Tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmInDomStr function <link linkend="IG31340177431"><command>pmInDomStr</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmLoadNameSpace function <link linkend="IG31340177296"><command>pmLoadNameSpace</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogconf command <link linkend="IG31340177255">Configuring PCP Tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogger command <link linkend="IG3134017776">Implementing a PMDA</link> <link linkend="IG31340177254">Configuring PCP Tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmLookupDesc function <link linkend="IG3134017788">Overview</link> <link linkend="IG31340177120">Data Structures</link> <link linkend="IG31340177163">Management of Evolution within a PMDA</link> <link linkend="IG31340177307"><command>pmLookupDesc</command> Function</link> <link linkend="IG31340177334">PMAPI Context Services</link> <link linkend="IG31340177368"><command>pmSetMode</command> Function</link> <link linkend="IG31340177421"><command>pmExtractValue</command> Function</link> <link linkend="IG31340177427"><command>pmConvScale</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmLookupInDom function <link linkend="IG31340177318"><command>pmLookupInDom</command> Function</link> <link linkend="IG31340177335">PMAPI Context Services</link> <link linkend="IG31340177366"><command>pmSetMode</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmLookupInDomArchive function <link linkend="IG31340177336">PMAPI Context Services</link> <link linkend="IG31340177409"><command>pmLookupInDomArchive</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmLookupInDomText function <link linkend="IG31340177310"><command>pmLookupInDomText</command> Function</link> <link linkend="IG31340177337">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmLookupName function <link linkend="IG3134017782nat">Overview</link> <link linkend="IG31340177298"><command>pmLookupName</command> Function</link> <link linkend="IG31340177338">PMAPI Context Services</link> <link linkend="IG31340177448">Symbolic Association between a Metric's Name and Value</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmLookupText function <link linkend="IG3134017790">Overview</link> <link linkend="IG31340177168">Management of Evolution within a PMDA</link> <link linkend="IG31340177285">Variable Length Argument and Results Lists</link> <link linkend="IG31340177312"><command>pmLookupText</command> Function</link> <link linkend="IG31340177339">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmNameAll function <link linkend="IG31340177299"><command>pmNameAll</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmNameID function <link linkend="IG31340177287">Variable Length Argument and Results Lists</link> <link linkend="IG31340177300"><command>pmNameID</command> Function</link> <link linkend="IG31340177340">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmNameInDom function <link linkend="IG31340177284">Variable Length Argument and Results Lists</link> <link linkend="IG31340177319"><command>pmNameInDom</command> Function</link> <link linkend="IG31340177341">PMAPI Context Services</link> <link linkend="IG31340177365"><command>pmSetMode</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmNameInDomArchive function <link linkend="IG31340177342">PMAPI Context Services</link> <link linkend="IG31340177410"><command>pmNameInDomArchive</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmNewContext function <link linkend="IG31340177350"><command>pmNewContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmNewContextZone function <link linkend="IG31340177379"><command>pmNewContextZone</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmNewZone function <link linkend="IG31340177380"><command>pmNewZone</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMNS</primaryie> + <secondaryie>acronym <link linkend="IG31340177577">Acronyms</link></secondaryie> + <secondaryie>distributed <link linkend="IG3134017729">Distributed PMNS</link></secondaryie> + <secondaryie>upgrade <link linkend="IG31340177245">Upgrading a PMNS to Include Metrics from a New PMDA</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmns man page <link linkend="IG31340177154">Name Space</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmNumberStr function <link linkend="IG31340177434"><command>pmNumberStr</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmParseInterval function <link linkend="IG31340177441"><command>pmParseInterval</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmParseMetricSpec function <link linkend="IG31340177442"><command>pmParseMetricSpec</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmprintf function <link linkend="IG31340177438"><command>pmprintf</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmPrintValue function <link linkend="IG31340177176">Management of Evolution within a PMDA</link> <link linkend="IG31340177436"><command>pmPrintValue</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmReconnectContext function <link linkend="IG31340177374"><command>pmReconnectContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmRecordAddHost function <link linkend="IG31340177394"><command>pmRecordAddHost</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmRecordControl function <link linkend="IG31340177397"><command>pmRecordControl</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmRecordSetup function <link linkend="IG31340177398"><command>pmRecordSetup</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmSetMode function <link linkend="IG31340177343">PMAPI Context Services</link> <link linkend="IG31340177371"><command>pmSetMode</command> Function</link> <link linkend="IG31340177404"><command>pmGetArchiveEnd</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmSortInstances function <link linkend="IG31340177439"><command>pmSortInstances</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmstore function <link linkend="IG3134017793">Overview</link> <link linkend="IG31340177117">Metrics</link> <link linkend="IG31340177171">Management of Evolution within a PMDA</link> <link linkend="IG31340177195"><literal>simple_store</literal> in the Simple PMDA</link> <link linkend="IG31340177235">Debugging Information</link> <link linkend="IG31340177276">Performance Metrics Values</link> <link linkend="IG31340177344">PMAPI Context Services</link> <link linkend="IG31340177392"><command>pmStore</command> Function</link> <link linkend="IG31340177393"><command>pmStore</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMTRACE_STATE_API flag <link linkend="IG31340177538">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMTRACE_STATE_ASYNC flag <link linkend="IG31340177547">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMTRACE_STATE_COMMS flag <link linkend="IG31340177539">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMTRACE_STATE_NOAGENT flag <link linkend="IG31340177543">Configuring the Trace Library</link> <link linkend="IG31340177544">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMTRACE_STATE_NONE flag <link linkend="IG31340177536">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMTRACE_STATE_PDU flag <link linkend="IG31340177540">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMTRACE_STATE_PDUBUF flag <link linkend="IG31340177541">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmtraceabort function <link linkend="IG31340177507">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmtracebegin function <link linkend="IG31340177504">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmtracend function <link linkend="IG31340177505">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmtraceobs function <link linkend="IG31340177518">Observations and Counters</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmtracepoint function <link linkend="IG31340177515">Point Tracing </link> <link linkend="IG31340177519">Observations and Counters</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmtracestate call <link linkend="IG31340177534">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmTraversePMNS function <link linkend="IG3134017786nat">Overview</link> <link linkend="IG31340177301"><command>pmTraversePMNS</command> Function</link> <link linkend="IG31340177345">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>__pmParseHostAttrsSpec function <link linkend="IG3134017790nat">Overview</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmTypeStr function <link linkend="IG31340177175">Management of Evolution within a PMDA</link> <link linkend="IG31340177432"><command>pmTypeStr</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmUnitsStr function <link linkend="IG31340177429"><command>pmUnitsStr</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmUnloadNameSpace function <link linkend="IG31340177304"><command>pmUnloadNameSpace</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmUnpackEventRecords function <link linkend="IG31340177280nat">Event Monitor Considerations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmUseContext function <link linkend="IG31340177353"><command>pmNewContext</command> Function</link> <link linkend="IG31340177356"><command>pmUseContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmUseZone function <link linkend="IG31340177381"><command>pmUseZone</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmWhichContext function <link linkend="IG31340177358"><command>pmWhichContext</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmWhichZone function <link linkend="IG31340177382"><command>pmWhichZone</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>point tracing <link linkend="IG31340177514">Point Tracing </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>program evolution <link linkend="IG31340177456">Accommodating Program Evolution</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>programming components <link linkend="IG313401771">Programming Performance Co-Pilot</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>protocol data units</primaryie> + <seeie>PDU</seeie> +</indexentry> + +<indexentry> + <primaryie>pthreads man page <link linkend="IG31340177152">Latency and Threads of Control</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>record-mode services <link linkend="IG31340177396"><command>pmRecordAddHost</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>removal script <link linkend="IG31340177248">Removing a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>restarting pmcd <link linkend="IG31340177242">Installing a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>retrospective analysis <link linkend="IG3134017730">Retrospective Sources of Performance Metrics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>ring buffers <link linkend="IG31340177490">Rolling-Window Periodic Sampling</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>rolling-window sampling <link linkend="IG31340177477">Sampling Techniques</link> <link linkend="IG31340177488">Rolling-Window Periodic Sampling</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>sample duration <link linkend="IG31340177489">Rolling-Window Periodic Sampling</link> <link linkend="IG31340177496">Configuring the Trace PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>sampling techniques <link linkend="IG31340177478">Sampling Techniques</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>scale and dimensionality <link linkend="IG31340177273">Performance Metric Descriptions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>semantic types <link linkend="IG31340177127">Semantics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>sequential log files <link linkend="IG3134017763">Implementing a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>service time <link linkend="IG31340177558">Instrumenting Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>simple periodic sampling <link linkend="IG31340177486">Simple Periodic Sampling</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>simple PMDA</primaryie> + <secondaryie>2 branches, 4 metrics <link linkend="IG31340177156">Name Space</link></secondaryie> + <secondaryie>as daemon <link linkend="IG31340177105">Daemon PMDA</link></secondaryie> + <secondaryie>DSO <link linkend="IG3134017797">DSO PMDA</link></secondaryie> + <secondaryie>initialization <link linkend="IG31340177216">Simple PMDA</link></secondaryie> + <secondaryie>pmdaFetch callback <link linkend="IG31340177188">Simple PMDA</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>simple_init function <link linkend="IG3134017799">DSO PMDA</link> <link linkend="IG31340177189">Simple PMDA</link> <link linkend="IG31340177217">Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>simple_store function <link linkend="IG31340177234">Debugging Information</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>simple.color metric <link linkend="IG31340177191">Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>simple.now metric <link linkend="IG31340177193">Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>simple.store metric <link linkend="IG31340177194"><literal>simple_store</literal> in the Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>simple.time metric <link linkend="IG31340177192">Simple PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>snapshot files <link linkend="IG3134017764">Implementing a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>software <link linkend="IG3134017732">Overview of Component Software</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>specific instance domain <link linkend="IG31340177346">PMAPI Context Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>state flags <link linkend="IG31340177523">Configuring the Trace Library</link> <link linkend="IG31340177532">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>storage of metrics <link linkend="IG31340177116">Metrics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>symbolic association <link linkend="IG31340177446">Symbolic Association between a Metric's Name and Value</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>synchronous protocol <link linkend="IG31340177537">Configuring the Trace Library</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>target domain <link linkend="IG3134017762">Implementing a PMDA</link> <link linkend="IG31340177115">Metrics</link> <link linkend="IG31340177148">Extracting the Information</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>TCP/IP <link linkend="IG31340177527">Configuring the Trace Library</link> <link linkend="IG31340177578">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>testing and debugging <link linkend="IG31340177226">Testing and Debugging a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>threaded applications <link linkend="IG3134017756">Library Reentrancy and Threaded Applications</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>time control services <link linkend="IG31340177414">PMAPI Time Control Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>timezone services <link linkend="IG31340177378"><command>pmNewContextZone</command> Function</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>tool configuration <link linkend="IG31340177250">Configuring PCP Tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace facilities <link linkend="IG313401776">Programming Performance Co-Pilot</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace PMDA</primaryie> + <secondaryie>command-line options <link linkend="IG31340177494">Configuring the Trace PMDA</link></secondaryie> + <secondaryie>description <link linkend="IG31340177462">Instrumenting Applications</link></secondaryie> + <secondaryie>design <link linkend="IG31340177470">Trace PMDA Design</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>trace.control.reset metric <link linkend="IG31340177501">Configuring the Trace PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.observe metrics <link linkend="IG31340177520">Observations and Counters</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.observe.rate metric <link linkend="IG31340177479">Sampling Techniques</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.point.count metric <link linkend="IG31340177516">Point Tracing </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.point.rate metric <link linkend="IG31340177517">Point Tracing </link> <link linkend="IG31340177480">Sampling Techniques</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.transact.ave_time metric <link linkend="IG31340177481">Sampling Techniques</link> <link linkend="IG31340177508">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.transact.count metric <link linkend="IG31340177509">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.transact.max_time metric <link linkend="IG31340177482">Sampling Techniques</link> <link linkend="IG31340177510">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.transact.min_time metric <link linkend="IG31340177483">Sampling Techniques</link> <link linkend="IG31340177511">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.transact.rate metric <link linkend="IG31340177484">Sampling Techniques</link> <link linkend="IG31340177512">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trace.transact.total_time metric <link linkend="IG31340177513">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>transactions <link linkend="IG31340177506">Transactions </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>trivial PMDA</primaryie> + <secondaryie>callbacks <link linkend="IG31340177186">Trivial PMDA</link></secondaryie> + <secondaryie>initialization <link linkend="IG31340177213">Trivial PMDA</link></secondaryie> + <secondaryie>singular metric <link linkend="IG31340177124">Data Structures</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>trivial_init function <link linkend="IG31340177187">Trivial PMDA</link> <link linkend="IG31340177215">Trivial PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>two or three dimensional arrays <link linkend="IG31340177135">N Dimensional Data</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>type field <link linkend="IG31340177170">Management of Evolution within a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>unavailable metrics support <link linkend="IG31340177162">Management of Evolution within a PMDA</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>working buffers <link linkend="IG31340177476">Application Interaction</link> <link linkend="IG31340177491">Rolling-Window Periodic Sampling</link></primaryie> +</indexentry> + +</index> + +</book> diff --git a/books/PCP_PG/publican.cfg b/books/PCP_PG/publican.cfg new file mode 100644 index 0000000..9be140f --- /dev/null +++ b/books/PCP_PG/publican.cfg @@ -0,0 +1,5 @@ +debug: 1 +xml_lang: en-US +brand: common +condition: common +tmp_dir: . diff --git a/books/PCP_TCS/Book_Info.xml b/books/PCP_TCS/Book_Info.xml new file mode 100644 index 0000000..653bb96 --- /dev/null +++ b/books/PCP_TCS/Book_Info.xml @@ -0,0 +1,15 @@ +<?xml version='1.0'?> +<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<bookinfo id="pcp-tutorials-and-case-studies"> + <title>pcp-tutorials-and-case-studies</title> + <subtitle>Performance Co-Pilot Tutorials and Case Studies</subtitle> + <edition>3</edition> + <productname>PCP</productname> + <productnumber>3</productnumber> + <pubsnumber>1</pubsnumber> + <xi:include href="Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>--> + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</bookinfo> diff --git a/books/PCP_TCS/GNUmakefile b/books/PCP_TCS/GNUmakefile new file mode 100644 index 0000000..aa41b16 --- /dev/null +++ b/books/PCP_TCS/GNUmakefile @@ -0,0 +1,61 @@ +TOPDIR = ../.. +include $(TOPDIR)/src/include/builddefs + +IAM = pcp-tutorials-and-case-studies +XML = $(IAM).xml +PDF = #$(IAM).pdf +PUB = Book_Info.xml +CFG = publican.cfg + +LSRCFILES = $(XML) $(PUB) $(CFG) $(PDF) +LDIRDIRT = pdf html en-US +LDIRT = built.* +CWD = $(shell pwd) + +default: build-me + +include $(BUILDRULES) + +ifeq "$(BOOK_TOOLCHAIN)" "publican" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf html en-US + @mkdir -p pdf html en-US/xml + $(LN_S) $(CWD)/$(PUB) en-US/ + $(LN_S) $(CWD)/$(XML) en-US/xml/ + $(LN_S) $(CWD)/$(TOPDIR)/images en-US/xml/figures + $(PUBLICAN) build --langs=en-US --formats=pdf + @# $(PUBLICAN) build --langs=en-US --formats=pdf,html + $(LN_S) $(CWD)/en-US/pdf/*.pdf pdf/$(IAM).pdf +endif + +ifeq "$(BOOK_TOOLCHAIN)" "dblatex" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf figures + $(LN_S) $(CWD)/$(TOPDIR)/images figures + $(DBLATEX) --type=pdf --output-dir=pdf $(XML) +endif + +ifeq "$(BOOK_TOOLCHAIN)" "xmlto" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf html figures + @mkdir -p pdf html + $(LN_S) $(CWD)/$(TOPDIR)/images pdf/figures + $(LN_S) $(CWD)/$(TOPDIR)/images html/figures + $(XMLTO) --with-fop -o pdf pdf $(XML) + $(XMLTO) --with-fop -o html html $(XML) +endif + +ifneq "$(findstring $(BOOK_TOOLCHAIN),publican dblatext xmlto)" "" +build-me: built.$(BOOK_TOOLCHAIN) + @touch built.$(BOOK_TOOLCHAIN) +else +build-me: +endif + +install: default +# $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR) +# $(INSTALL) -m 644 $(PDF) $(PCP_BOOKS_DIR)/$(PDF) + +default_pcp : default + +install_pcp : install diff --git a/books/PCP_TCS/pcp-tutorials-and-case-studies.pdf b/books/PCP_TCS/pcp-tutorials-and-case-studies.pdf Binary files differnew file mode 100644 index 0000000..5027413 --- /dev/null +++ b/books/PCP_TCS/pcp-tutorials-and-case-studies.pdf diff --git a/books/PCP_TCS/pcp-tutorials-and-case-studies.xml b/books/PCP_TCS/pcp-tutorials-and-case-studies.xml new file mode 100644 index 0000000..a5eda02 --- /dev/null +++ b/books/PCP_TCS/pcp-tutorials-and-case-studies.xml @@ -0,0 +1,334 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<book status="final" security="public"><title>Performance Co-Pilot™ Tutorials and Case Studies</title> +<bookinfo><edition>3</edition> + +<othercredit> +<contrib>Maintained by</contrib> +<affiliation> +<orgname>The Performance Co-Pilot Development Team</orgname> +<address> +<email>pcp@mail.performancecopilot.org</email> +<otheraddr> +<ulink url="http://www.performancecopilot.org"/> +<inlinemediaobject><imageobject><imagedata fileref="figures/pcp.svg"/></imageobject></inlinemediaobject> +</otheraddr> +</address> +</affiliation> +</othercredit> + +<copyright> +<year>2012</year> +<year>2014</year> +<holder>Red Hat, Inc.</holder> +</copyright> + +<copyright> +<year>2007</year> +<year>2013</year> +<holder>Aconex.</holder> +</copyright> + +<copyright> +<year>2000</year> +<year>2013</year> +<holder>Silicon Graphics, Inc.</holder> +</copyright> + +<legalnotice> +<title>LICENSE</title> +<para>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 +<ulink url="http://creativecommons.org/licenses/by-sa/3.0/us/"/></para> +</legalnotice> + +<legalnotice> +<title>TRADEMARKS AND ATTRIBUTIONS</title> +<para>Red Hat and the Shadowman logo are trademarks of Red Hat, Inc., +registered in the United States and other countries.</para> +<para>Silicon Graphics, SGI and the SGI logo are registered trademarks +and Performance Co-Pilot is a trademark of Silicon Graphics, Inc.</para> +<para>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.</para> +</legalnotice> + +<revhistory> +<revision><revnumber>001</revnumber><date>August 2013</date><revremark>Initial collation.</revremark></revision> +</revhistory> + +</bookinfo> +<toc/> + + +<preface id="id5178752"> + +<title>About This Book</title> +<para>This book is a collection of tutorials, case studies, and short stories about +various aspects of the Performance Co-Pilot (PCP) performance analysis toolkit. +Topics range from basic installation through to detailed analysis techniques, +with everything in-between, that even seasoned PCP users can expect to learn from. +</para> +<para>Much like PCP is an open source, cross-platform software package - where +customizations are actively encouraged - so too is this book. If you have +interesting experiences to share, please consider contibuting - the XML source +to this book is available, along with the PCP source code.</para> +<para>“About This Book” includes short descriptions of the chapters +in this book, directs you to additional sources of information, and explains +typographical conventions.</para> +<section id="id5178771"> + +<title>What This Book Contains</title> +<para>This book contains the following chapters:</para> +<itemizedlist> +<listitem><para><xref linkend="LE21795-PARENT"/>, contains introductory topics around installation of PCP.</para> +</listitem> +<listitem><para><xref linkend="LE98072-PARENT"/>, contains a series of hands-on tutorials covering use of specific PCP monitor tools, secure collector setup.</para> +</listitem> +<listitem><para><xref linkend="LE25915-PARENT"/>, provides a set of case studies of use of PCP to address problems, or understand certain system behaviours using PCP.</para> +</listitem></itemizedlist> +<para>It provides a series of real-world examples of using various PCP tools, +and lessons learned from deploying the toolkit in production environments. +It serves to provide reinforcement of the general concepts discussed in the +other books described in the <xref linkend="id5178933"/>, with additional case +studies and more detailed discussion of individual tools.</para> +</section> +<section id="id5178891"> + +<title>Audience for This Book</title> +<para>This book has something for everyone - early topics will aid those getting +started with PCP, while later sections cover in-depth material, sometimes requiring +detailed understanding of operating system internals.</para> +<para>Some familiarity with the basic concepts behind PCP is assumed.</para> +</section> +<section id="id5178933"> + +<title>Related Resources</title> +<para>The <citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle> +is intended for system administrators and performance analysts who are directly +using and administering PCP installations.</para> +<para>The <citetitle>Performance Co-Pilot Programmer's Guide</citetitle> +is intended for developers who want to use the PCP framework and services for +exporting additional collections of performance metrics, or for delivering +new or customized applications to enhance performance management. +</para> +<para>Additional resources include man pages and the project web site.</para> +</section> +<section id="id5178968"> + +<title>Man Pages</title> +<para>The operating system man pages provide concise reference information on the use of commands, subroutines, and system resources. There is usually a man page for each PCP command or subroutine. To see a list of all the PCP man pages, start from the following command:</para> +<literallayout class="monospaced"><userinput>man PCPIntro</userinput></literallayout> +<para>Each man page usually has a "SEE ALSO" section, linking to other, related entries.</para> +<para>To see a particular man page, supply its name to the <literal>man</literal> command, for example:</para> +<literallayout class="monospaced"><userinput>man pcp</userinput></literallayout> +<para>The man pages are arranged in different sections separating commands, programming interfaces, and so on. +For a complete list of manual sections on a platform enter the command:</para> +<literallayout class="monospaced"><userinput>man man</userinput></literallayout> +<para>When referring to man pages, this guide follows a standard convention: the section number in parentheses follows the item. For example, <command>pminfo(1)</command> refers to the man page in section 1 for the <command>pminfo</command> command.</para> +</section> +<section id="id5179157"> + +<title>Web Site</title> +<para>The following web site is accessible to everyone:</para> +<variablelist condition="sgi_termlength:wide"> +<varlistentry> +<term><emphasis role="bold">URL</emphasis></term><listitem><para><emphasis role="bold">Description</emphasis></para></listitem></varlistentry> +<varlistentry> +<term><ulink url="http://www.performancecopilot.org">http://www.performancecopilot.org</ulink></term> +<listitem><para>PCP is open source software released under +the GNU General Public License (GPL) and GNU Lesser General Public License (LGPL)</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5179276"> + +<title>Conventions</title> +<para>The following conventions are used throughout this document:<variablelist> +<varlistentry> +<term><emphasis role="bold">Convention</emphasis></term><listitem><para><emphasis role="bold">Meaning</emphasis></para></listitem></varlistentry> +<varlistentry> +<term><literal>${PCP_VARIABLE}</literal></term> +<listitem><para>A brace-enclosed all-capital-letters syntax indicates a variable +that has been sourced from the global <filename>/etc/pcp.conf</filename> file. +These special variables indicate parameters that affect all PCP commands, +and are likely to be different between platforms.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><literal>command</literal></term> +<listitem><para>This fixed-space font denotes literal items such as commands, +files, routines, path names, signals, messages, and programming language +structures. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><replaceable>variable</replaceable></term> +<listitem><para>Italic typeface denotes variable entries and words or concepts being +defined.</para> +</listitem></varlistentry> + +<varlistentry> +<term><userinput>user input</userinput></term> +<listitem><para>This bold, fixed-space font denotes literal items that the user enters in interactive sessions. (Output is shown in nonbold, fixed-space font.)</para> +</listitem></varlistentry> + +<varlistentry> +<term>[ ]</term> +<listitem><para>Brackets enclose optional portions of a command or directive line.</para> +</listitem></varlistentry> + +<varlistentry> +<term>...</term> +<listitem><para>Ellipses indicate that a preceding element can be repeated.</para> +</listitem></varlistentry> +<varlistentry> +<term>ALL CAPS</term> +<listitem><para>All capital letters denote environment variables, operator names, directives, defined constants, and macros in C programs.</para> +</listitem></varlistentry> +<varlistentry> +<term>()</term> +<listitem><para>Parentheses that follow function names surround function arguments or are empty if the function has no arguments; parentheses that follow commands surround man page section numbers.</para> +</listitem></varlistentry> +</variablelist></para> + +</section> +<section id="z825546061melby"> + +<title>Reader Comments</title> +<para>If you have comments about the technical accuracy, content, or organization of this document, contact the PCP maintainers using either the email address or the web site listed earlier.</para> +<para>We value your comments and will respond to them promptly.</para> +</section> +</preface> + + +<chapter id="LE21795-PARENT"> + +<title>Supported Platforms Installation</title> +<para>Binary packages for Linux (deb and rpm formats), Mac OS X, Solaris and Windows are +made available by the PCP development team.</para> +<para>These are all freely available from the download section of the PCP project web site.</para> + +<section id="id5177140"> + +<title>Linux Installation</title> +<para><indexterm id="IG313401778"><primary>Linux</primary></indexterm>Pre-packaged binaries are available for the Linux platform ... XXX</para> +</section> +<section id="id5177343"> + +<title>Mac OS X Installation</title> +<para><indexterm id="IG313401779"><primary>Mac OS X</primary></indexterm>After downloading the <literal>dmg</literal> file for your platform, double-click on the PCP <literal>dmg</literal> icon in the Finder application, and follow the installation instructions presented by the Installer.</para> +<para>Mac OS X versions 10.5 and onward are generally available, although older versions can be built from source.</para> +</section> +<section id="id5177529"> + +<title>Solaris Installation</title> +<para><indexterm id="IG313401780"><primary>Solaris</primary></indexterm>Download and unzip the latest binary package from the PCP project web site.</para> +<para>To install the package for the first time, issue the following commands:</para> +<programlisting><userinput>pkgadd -d pcp-${PCP_VERSION}</userinput> + Say 'y' to all of the questions. +<userinput>svcadm enable pmcd</userinput></programlisting> +<para>To upgrade an existing installation, issue the following commands:</para> +<programlisting><userinput>pkgadd -d pcp-${PCP_VERSION}</userinput> +<userinput>pkgadd -d pcp-${PCP_VERSION}</userinput> +<userinput>svcadm enable pmcd</userinput></programlisting> +</section> +<section id="id5177616"> + +<title>Windows Installation</title> +<para><indexterm id="IG313401781"><primary>Windows</primary></indexterm> After downloading the PCP Glider <literal>msi</literal> file, right-click on the command prompt icon, select <literal>Run As Administrator</literal>, and enter:</para> +<programlisting><userinput>msiexec /i pcp-glider-${PCP_VERSION}.msi</userinput> +<userinput>cd C:\Glider\scripts</userinput> +<userinput>postinst.bat</userinput></programlisting> +<para>The command line utilities can now be accessed from a Windows shell or the provided (POSIX) shell. The graphical tools can be accessed via the Windows <literal>Start</literal> menu.</para> +</section> +</chapter> + + +<chapter id="LE98072-PARENT"> + +<title>Tutorials</title> +<para>From a high-level PCP can be considered to contain two classes of software utility:</para> +<itemizedlist> +<listitem><para>PCP Collectors. These are the parts of PCP that collect and extract performance data from various domains, such as the kernel or a database.</para> +</listitem> +<listitem><para>PCP Monitors. These are the parts of PCP that display data collected from hosts (or archives) that have the PCP Collector installed.</para> +</listitem></itemizedlist> +<para>The tutorials of this section focus on various monitoring tools initially, and then finish up with some extensions to collector systems not covered in the <citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle>.</para> + +<section id="id5187772"> +<title>Using PCP Charts</title> +<para>...</para> +</section> + +<section id="id5188149"> +<title>Logging Basics</title> +<para>...</para> +</section> + +<section id="id5188221"> +<title>Automated Reasoning</title> +<para>...</para> +</section> + + +</chapter> + + +<chapter id="LE25915-PARENT"> +<title>Case Studies</title> + +<section id="id5187771"> +<title>Understanding System-Level Processor Performance</title> +<para>...</para> +</section> + +<section id="id5187773"> +<title>Understanding Measures of Disk Performance</title> +<para>...</para> +</section> + +<section id="id5187774"> +<title>An Operating System Upgrade Evaluation</title> +<para>...</para> +</section> + +<section id="id5187775"> +<title>Comparing Storage System Performance</title> +<para>...</para> +</section> + +<section id="id5187776"> +<title>Central Logging: Instrumenting Distributed Event Logs</title> +<para>...</para> +</section> + + +</chapter> + + +<index id="sgi-index"> + +<indexentry> + <primaryie>Linux <link linkend="IG313401778">Supported Platforms Installation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Max OS X <link linkend="IG313401779">Supported Platform Installations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Solaris <link linkend="IG313401780">Supported Platform Installations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Windows <link linkend="IG313401781">Supported Platforms Installation</link></primaryie> +</indexentry> + +</index> + +</book> diff --git a/books/PCP_TCS/publican.cfg b/books/PCP_TCS/publican.cfg new file mode 100644 index 0000000..9be140f --- /dev/null +++ b/books/PCP_TCS/publican.cfg @@ -0,0 +1,5 @@ +debug: 1 +xml_lang: en-US +brand: common +condition: common +tmp_dir: . diff --git a/books/PCP_UAG/Book_Info.xml b/books/PCP_UAG/Book_Info.xml new file mode 100644 index 0000000..dda0261 --- /dev/null +++ b/books/PCP_UAG/Book_Info.xml @@ -0,0 +1,14 @@ +<?xml version='1.0'?> +<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> +<bookinfo id="pcp-users-and-administrators-guide"> + <title>pcp-users-and-administrators-guide</title> + <subtitle>Performance Co-Pilot User's and Administrator's Guide</subtitle> + <edition>3</edition> + <productname>PCP</productname> + <productnumber>3</productnumber> + <pubsnumber>1</pubsnumber> + <xi:include href="Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>--> + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</bookinfo> diff --git a/books/PCP_UAG/GNUmakefile b/books/PCP_UAG/GNUmakefile new file mode 100644 index 0000000..06ce845 --- /dev/null +++ b/books/PCP_UAG/GNUmakefile @@ -0,0 +1,61 @@ +TOPDIR = ../.. +include $(TOPDIR)/src/include/builddefs + +IAM = pcp-users-and-administrators-guide +XML = $(IAM).xml +PDF = $(IAM).pdf +PUB = Book_Info.xml +CFG = publican.cfg + +LSRCFILES = $(XML) $(PUB) $(CFG) $(PDF) +LDIRDIRT = pdf html en-US +LDIRT = built.* +CWD = $(shell pwd) + +default: build-me + +include $(BUILDRULES) + +ifeq "$(BOOK_TOOLCHAIN)" "publican" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf html en-US + @mkdir -p pdf html en-US/xml + $(LN_S) $(CWD)/$(PUB) en-US/ + $(LN_S) $(CWD)/$(XML) en-US/xml/ + $(LN_S) $(CWD)/$(TOPDIR)/images en-US/xml/figures + $(PUBLICAN) build --langs=en-US --formats=pdf + @# $(PUBLICAN) build --langs=en-US --formats=pdf,html + $(LN_S) $(CWD)/en-US/pdf/*.pdf pdf/$(IAM).pdf +endif + +ifeq "$(BOOK_TOOLCHAIN)" "dblatex" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf figures + $(LN_S) $(CWD)/$(TOPDIR)/images figures + $(DBLATEX) --type=pdf --output-dir=pdf $(XML) +endif + +ifeq "$(BOOK_TOOLCHAIN)" "xmlto" +built.$(BOOK_TOOLCHAIN): $(XML) + @rm -fr pdf html figures + @mkdir -p pdf html + $(LN_S) $(CWD)/$(TOPDIR)/images pdf/figures + $(LN_S) $(CWD)/$(TOPDIR)/images html/figures + $(XMLTO) --with-fop -o pdf pdf $(XML) + $(XMLTO) --with-fop -o html html $(XML) +endif + +ifneq "$(findstring $(BOOK_TOOLCHAIN),publican dblatext xmlto)" "" +build-me: built.$(BOOK_TOOLCHAIN) + @touch built.$(BOOK_TOOLCHAIN) +else +build-me: +endif + +install: default + $(INSTALL) -m 755 -d $(PCP_BOOKS_DIR) + $(INSTALL) -m 644 $(PDF) $(PCP_BOOKS_DIR)/$(PDF) + +default_pcp : default + +install_pcp : install diff --git a/books/PCP_UAG/pcp-users-and-administrators-guide.pdf b/books/PCP_UAG/pcp-users-and-administrators-guide.pdf Binary files differnew file mode 100644 index 0000000..6954be3 --- /dev/null +++ b/books/PCP_UAG/pcp-users-and-administrators-guide.pdf diff --git a/books/PCP_UAG/pcp-users-and-administrators-guide.xml b/books/PCP_UAG/pcp-users-and-administrators-guide.xml new file mode 100644 index 0000000..f869222 --- /dev/null +++ b/books/PCP_UAG/pcp-users-and-administrators-guide.xml @@ -0,0 +1,8020 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<book status="final" security="public"><title>Performance Co-Pilot™ User's and Administrator's Guide</title> +<bookinfo><edition>3</edition> + +<othercredit> +<contrib>Maintained by</contrib> +<affiliation> +<orgname>The Performance Co-Pilot Development Team</orgname> +<address> +<email>pcp@mail.performancecopilot.org</email> +<otheraddr> +<ulink url="http://www.performancecopilot.org"/> +<inlinemediaobject><imageobject><imagedata fileref="figures/pcp.svg"/></imageobject></inlinemediaobject> +</otheraddr> +</address> +</affiliation> +</othercredit> + +<copyright> +<year>2000</year> +<year>2013</year> +<holder>Silicon Graphics, Inc.</holder> +</copyright> + +<copyright> +<year>2013</year> +<year>2014</year> +<holder>Red Hat, Inc.</holder> +</copyright> + +<legalnotice> +<title>LICENSE</title> +<para>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 +<ulink url="http://creativecommons.org/licenses/by-sa/3.0/us/"/></para> +</legalnotice> + +<legalnotice> +<title>TRADEMARKS AND ATTRIBUTIONS</title> +<para>Silicon Graphics, SGI and the SGI logo are registered trademarks +and Performance Co-Pilot is a trademark of Silicon Graphics, Inc.</para> +<para>Red Hat and the Shadowman logo are trademarks of Red Hat, Inc., +registered in the United States and other countries.</para> +<para>Cisco is a 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.</para> +</legalnotice> + +<revhistory> +<revision><revnumber>002</revnumber><date>August 2013</date><revremark>Revised to support the Performance Co-Pilot 3.8 release.</revremark></revision> +<revision><revnumber>001</revnumber><date>December 2002</date><revremark>Original publication. Supports the Performance Co-Pilot 2.3 release.</revremark></revision> +</revhistory> + +</bookinfo> +<toc/> + + +<preface id="id5178699"> + +<title>About This Guide</title> +<para>This guide describes the Performance Co-Pilot (PCP) performance analysis toolkit. +PCP provides a systems-level suite of tools that cooperate to deliver +distributed performance monitoring and performance management services spanning +hardware platforms, operating systems, service layers, database internals, +user applications and distributed architectures.</para> +<para>PCP is a cross-platform, open source software package - customizations, extensions, +source code inspection, and tinkering in general is actively encouraged.</para> +<para>“About This Guide” includes short descriptions of the chapters +in this book, directs you to additional sources of information, and explains +typographical conventions.</para> +<section id="id5178738"> + +<title>What This Guide Contains</title> +<para>This guide contains the following chapters:</para> +<itemizedlist> +<listitem><para><xref linkend="LE91944-PARENT"/>, provides an introduction, +a brief overview of the software components, and conceptual foundations of +the PCP software.</para> +</listitem> +<listitem><para><xref linkend="LE17127-PARENT"/>, describes the basic installation +and configuration steps necessary to get PCP running on your systems.</para> +</listitem> +<listitem><para><xref linkend="LE94335-PARENT"/>, describes the user interface +components that are common to most of the text-based utilities that make up +the monitor portion of PCP.</para> +</listitem> +<listitem><para><xref linkend="LE38515-PARENT"/>, describes the performance +monitoring tools available in Performance Co-Pilot (PCP). </para> +</listitem> +<listitem><para><xref linkend="LE21414-PARENT"/>, describes the Performance +Metrics Inference Engine (<command>pmie</command>) tool that provides automated +monitoring of, and reasoning about, system performance within the PCP framework. +</para> +</listitem> +<listitem><para><xref linkend="LE93354-PARENT"/>, covers the PCP services and +utilities that support archive logging for capturing accurate historical performance +records.</para> +</listitem> +<listitem><para><xref linkend="LE83321-PARENT"/>, presents the various options +for deploying PCP functionality across cooperating systems.</para> +</listitem> +<listitem><para><xref linkend="LE62564-PARENT"/>, describes the procedures +necessary to ensure that the PCP configuration is customized in ways that +maximize the coverage and quality of performance monitoring and management +services.</para> +</listitem> +<listitem><para><xref linkend="LE65325-PARENT"/>, provides a comprehensive +list of the acronyms used in this guide and in the man pages for Performance +Co-Pilot.</para> +</listitem></itemizedlist> +</section> +<section id="id5178921"> + +<title>Audience for This Guide</title> +<para>This guide is written for the system administrator or performance analyst +who is directly using and administering PCP applications.</para> +</section> +<section id="id5178935"> + +<title>Related Resources</title> +<para>The <citetitle>Performance Co-Pilot Programmer's Guide</citetitle>, +a companion document to the +<citetitle>Performance Co-Pilot User's and Administrator's Guide</citetitle>, +is intended for developers who want to use the PCP framework and services for +exporting additional collections of performance metrics, or for delivering +new or customized applications to enhance performance management. +</para> +<para>The <citetitle>Performance Co-Pilot Tutorials and Case Studies</citetitle> +provides a series of real-world examples of using various PCP tools, and +lessons learned from deploying the toolkit in production environments. +It serves to provide reinforcement of the general concepts discussed in the +other two books with additional case studies, and in some cases very detailed +discussion of specifics of individual tools. +</para> +<para>Additional resources include man pages and the project web site.</para> +</section> +<section id="id5178967"> + +<title>Man Pages</title> +<para>The operating system man pages provide concise reference information on the use of commands, subroutines, and system resources. There is usually a man page for each PCP command or subroutine. To see a list of all the PCP man pages, start from the following command:</para> +<literallayout class="monospaced"><userinput>man PCPIntro</userinput></literallayout> +<para>Each man page usually has a "SEE ALSO" section, linking to other, related entries.</para> +<para>To see a particular man page, supply its name to the <literal>man</literal> command, for example:</para> +<literallayout class="monospaced"><userinput>man pcp</userinput></literallayout> +<para>The man pages are arranged in different sections - user commands, programming interfaces, and so on. +For a complete list of manual sections on a platform enter the command:</para> +<literallayout class="monospaced"><userinput>man man</userinput></literallayout> +<para>When referring to man pages, this guide follows a standard convention: the section number in parentheses follows the item. +For example, <command>pminfo(1)</command> refers to the man page in section 1 for the <command>pminfo</command> command.</para> +</section> +<section id="id5178968"> + +<title>Web Site</title> +<para>The following web site is accessible to everyone:</para> +<variablelist condition="sgi_termlength:wide"> +<varlistentry> +<term><emphasis role="bold">URL</emphasis></term><listitem><para><emphasis role="bold">Description</emphasis></para></listitem></varlistentry> +<varlistentry> +<term><ulink url="http://www.performancecopilot.org">http://www.performancecopilot.org</ulink></term> +<listitem><para>PCP is open source software released under +the GNU General Public License (GPL) and GNU Lesser General Public License (LGPL)</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5179060"> + +<title>Conventions</title> +<para>The following conventions are used throughout this document:<variablelist> +<varlistentry> +<term><emphasis role="bold">Convention</emphasis></term><listitem><para><emphasis role="bold">Meaning</emphasis></para></listitem></varlistentry> +<varlistentry> +<term><literal>${PCP_VARIABLE}</literal></term> +<listitem><para>A brace-enclosed all-capital-letters syntax indicates a variable +that has been sourced from the global <filename>${PCP_DIR}/etc/pcp.conf</filename> file. +These special variables indicate parameters that affect all PCP commands, +and are likely to be different between platforms.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><literal>command</literal></term> +<listitem><para>This fixed-space font denotes literal items such as commands, +files, routines, path names, signals, messages, and programming language +structures. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><replaceable>variable</replaceable></term> +<listitem><para>Italic typeface denotes variable entries and words or concepts being +defined.</para> +</listitem></varlistentry> + +<varlistentry> +<term><userinput>user input</userinput></term> +<listitem><para>This bold, fixed-space font denotes literal items that the user enters in interactive sessions. (Output is shown in nonbold, fixed-space font.)</para> +</listitem></varlistentry> + +<varlistentry> +<term>[ ]</term> +<listitem><para>Brackets enclose optional portions of a command or directive line.</para> +</listitem></varlistentry> + +<varlistentry> +<term>...</term> +<listitem><para>Ellipses indicate that a preceding element can be repeated.</para> +</listitem></varlistentry> +<varlistentry> +<term>ALL CAPS</term> +<listitem><para>All capital letters denote environment variables, operator +names, directives, defined constants, and macros in C programs.</para> +</listitem></varlistentry> +<varlistentry> +<term>()</term> +<listitem><para>Parentheses that follow function names surround function arguments +or are empty if the function has no arguments; parentheses that follow commands +surround man page section numbers.</para> +</listitem></varlistentry> +</variablelist></para> +</section> +<section id="z825546061melby"> + +<title>Reader Comments</title> +<para>If you have comments about the technical accuracy, content, or organization of this document, contact the PCP maintainers using either the email address or the web site listed earlier.</para> +<para>We value your comments and will respond to them promptly.</para> +</section> +</preface> + + +<chapter id="LE91944-PARENT"> + +<title>Introduction to PCP</title> +<para><indexterm id="ITch01-0"><primary>overview</primary></indexterm><indexterm id="IG313718880"> +<primary>PCP</primary><secondary>features</secondary></indexterm><indexterm id="IG313718881"> +<primary>Performance Co-Pilot</primary><see>PCP</see></indexterm>This +chapter provides an introduction to Performance Co-Pilot (PCP), an overview +of its individual components, and conceptual information to help you use +this software.</para> +<para>The following sections are included:</para> +<itemizedlist> +<listitem><para><xref linkend="LE92676-PARENT"/> covers the intended purposes of PCP.</para></listitem> +<listitem><para><xref linkend="LE13618-PARENT"/>, describes PCP tools and agents.</para></listitem> +<listitem><para><xref linkend="LE79836-PARENT"/>, discusses the design theories behind PCP.</para></listitem> +</itemizedlist> +<section id="LE92676-PARENT"> + +<title>Objectives</title> +<para><indexterm id="IG313718882"><primary>objectives</primary></indexterm></para> +<para>Performance Co-Pilot (PCP) provides a range of services that may +be used to monitor and manage system performance. These services are distributed +and scalable to accommodate the most complex system configurations and +performance problems.</para> +<section id="LE67354-PARENT"> + +<title>PCP Target Usage</title> +<para><indexterm id="IG313718883"><primary>target usage</primary></indexterm>PCP is targeted +at the performance analyst, benchmarker, capacity planner, developer, +database administrator, or system administrator with an interest in overall +system performance and a need to quickly isolate and understand performance +behavior, resource utilization, activity levels, and bottlenecks in complex +systems. Platforms that can benefit from this level of performance analysis +include large servers, server clusters, or multiserver sites delivering +Database Management Systems (DBMS), compute, Web, file, or video services. +</para> +</section> +<section id="LE79006-PARENT"> + +<title>Empowering the PCP User</title> +<para><indexterm id="IG313718884"><primary>audience</primary></indexterm>To deal efficiently +with the dynamic behavior of complex systems, performance analysts need +to filter out noise from the overwhelming stream of performance data, +and focus on exceptional scenarios. Visualization of current and historical +performance data, and automated reasoning about performance data, effectively +provide this filtering.</para> +<para>From the PCP end user's perspective, PCP presents an integrated +suite of tools, user interfaces, and services that support real-time and +retrospective performance analysis, with a bias towards eliminating mundane +information and focusing attention on the exceptional and extraordinary +performance behaviors. When this is done, the user can concentrate on +in-depth analysis or target management procedures for those critical system +performance problems.</para> +</section> +<section id="LE35382-PARENT"> + +<title>Unification of Performance Metric Domains</title> +<para><indexterm id="IG313718885"><primary>domains</primary></indexterm><indexterm id="IG313718886"><primary> +metric domains</primary></indexterm>At the lowest level, performance metrics +are collected and managed in autonomous performance domains such as the +operating system kernel, a DBMS, a layered service, or an end-user application. +These domains feature a multitude of access control policies, access methods, +data semantics, and multiversion support. All this detail is irrelevant +to the developer or user of a performance monitoring tool, and is hidden +by the PCP infrastructure.</para> +<para><indexterm id="IG313718887"><primary>PMDA</primary><secondary>unification</secondary> +</indexterm><indexterm id="IG313718888"><primary>Performance Metrics Domain Agent</primary> +<see>PMDA</see></indexterm>Performance Metrics Domain Agents (PMDAs) within +PCP encapsulate the knowledge about, and export performance information +from, autonomous performance domains.</para> +</section> +<section id="LE83994-PARENT"> + +<title>Uniform Naming and Access to Performance Metrics +</title> +<para><indexterm id="IG313718889"><primary>uniform naming</primary></indexterm><indexterm id="IG3137188810"> +<primary>naming scheme</primary></indexterm><indexterm id="IG3137188811"><primary>PMNS</primary> +<secondary>defined names</secondary></indexterm><indexterm id="IG3137188812"><primary>Performance +Metrics Name Space</primary><see>PMNS</see></indexterm>Usability and extensibility +of performance management tools mandate a single scheme for naming performance +metrics. The set of defined names constitutes a Performance Metrics Name +Space (PMNS). Within PCP, the PMNS is adaptive so it can be extended, +reshaped, and pruned to meet the needs of particular applications and +users.</para> +<para>PCP provides a single interface to name and retrieve values for +all performance metrics, independently of their source or location.</para> +</section> +<section id="LE85063-PARENT"> + +<title>PCP Distributed Operation</title> +<para><indexterm id="ITch01-2"><primary>PCP</primary><secondary>distributed +operation</secondary></indexterm>From a purely pragmatic viewpoint, a +single workstation must be able to monitor the concurrent performance +of multiple remote hosts. At the same time, a single host may be subject +to monitoring from multiple remote workstations.</para> +<para><indexterm id="IG3137188813"><primary>client-server architecture</primary></indexterm>These +requirements suggest a classic client-server architecture, which is exactly +what PCP uses to provide concurrent and multiconnected access to performance +metrics, independent of their host location.</para> +</section> +<section id="LE87326-PARENT"> + +<title>Dynamic Adaptation to Change</title> +<para><indexterm id="IG3137188814"><primary>dynamic adaptation</primary></indexterm><indexterm id="IG3137188815"> +<primary>adaptation</primary></indexterm>Complex systems are subject to +continual changes as network connections fail and are reestablished; nodes +are taken out of service and rebooted; hardware is added and removed; +and software is upgraded, installed, or removed. Often these changes are +asynchronous and remote (perhaps in another geographic region or domain +of administrative control).</para> +<para>The distributed nature of the PCP (and the modular fashion in which +performance metrics domains can be installed, upgraded, and configured +on different hosts) enables PCP to adapt concurrently to changes in the +monitored system(s). Variations in the available performance metrics as +a consequence of configuration changes are handled automatically and become +visible to all clients as soon as the reconfigured host is rebooted or +the responsible agent is restarted.</para> +<para>PCP also detects loss of client-server connections, and most clients +support subsequent automated reconnection.</para> +</section> +<section id="LE13859-PARENT"> + +<title>Logging and Retrospective Analysis</title> +<para><indexterm id="IG3137188816"><primary>archive logs</primary><secondary>analysis</secondary> +</indexterm><indexterm id="ITch01-3"><primary>logging</primary><see>archive +logs</see></indexterm>A range of tools is provided to support flexible, +adaptive logging of performance metrics for archive, playback, remote +diagnosis, and capacity planning. PCP archive logs may be accumulated +either at the host being monitored, at a monitoring workstation, or both. +</para> +<para>A universal replay mechanism, modeled on +<ulink url="http://en.wikipedia.org/wiki/Media_controls">media controls</ulink>, +supports play, step, rewind, fast forward and variable speed processing of archived +performance data. Replay for multiple archives, from multiple hosts, is facilitated +by an archive aggregation concept.</para> +<para>Most PCP applications are able to process archive logs and real-time +performance data with equal facility. Unification of real-time access +and access to the archive logs, in conjunction with the media controls, +provides powerful mechanisms for building performance tools and to review +both current and historical performance data.</para> +</section> +<section id="LE36677-PARENT"> + +<title>Automated Operational Support</title> +<para><indexterm id="IG3137188817"><primary>automated operational support</primary></indexterm>For +operational and production environments, PCP provides a framework with +scripts to customize in order to automate the execution of ongoing tasks +such as these:</para> +<itemizedlist> +<listitem><para><indexterm id="IG3137188818"><primary>centralized archive logging</primary> +</indexterm>Centralized archive logging for multiple remote hosts</para> +</listitem> +<listitem><para><indexterm id="IG3137188819"><primary>archive logs</primary><secondary> +customization</secondary></indexterm>Archive log rotation, consolidation, +and culling</para> +</listitem> +<listitem><para>Web-based publishing of charts showing snapshots of performance +activity levels in the recent past</para> +</listitem> +<listitem><para>Flexible alarm monitoring: parameterized rules to address +common critical performance scenarios and facilities to customize and +refine this monitoring</para> +</listitem> +<listitem><para><indexterm id="IG3137188820"><primary>audits</primary></indexterm>Retrospective +performance audits covering the recent past; for example, daily or weekly +checks for performance regressions or quality of service problems</para> +</listitem></itemizedlist> +</section> +<section id="LE38522-PARENT"> + +<title>PCP Extensibility</title> +<para><indexterm id="IG3137188821"><primary>extensibility</primary></indexterm><indexterm id="IG3137188822"> +<primary>PCP</primary><secondary>extensibility</secondary></indexterm>PCP +permits the integration of new performance metrics into the PMNS, the +collection infrastructure, and the logging framework. The guiding principle +is, “if it is important for monitoring system performance, and you +can measure it, you can easily integrate it into the PCP framework.” +</para> +<para>For many PCP users, the most important performance metrics are +not those already supported, but new performance metrics that characterize +the essence of good or bad performance at their site, or within their +particular application environment.</para> +<para>One example is an application that measures the round-trip time +for a benign “probe” transaction against some mission-critical +application.</para> +<para><indexterm id="IG3137188823"><primary>PMDA</primary><secondary>libraries</secondary> +</indexterm>For application developers, a library is provided to support +easy-to-use insertion of trace and monitoring points within an application, +and the automatic export of resultant performance data into the PCP framework. +Other libraries and tools aid the development of customized and fully +featured Performance Metrics Domain Agents (PMDAs).</para> +<para>Extensive source code examples are provided in the distribution, +and by using the PCP toolkit and interfaces, these customized measures +of performance or quality of service can be easily and seamlessly integrated +into the PCP framework.</para> +</section> +<section id="LE40772-PARENT"> + +<title>Metric Coverage</title> +<para><indexterm id="IG3137188824"><primary>coverage</primary></indexterm>The core +PCP modules support export of performance metrics that include kernel +instrumentation, hardware instrumentation, process-level resource utilization, +database and other system services instrumentation, and activity in the PCP +collection infrastructure.</para> +<para>The supplied agents support thousands of distinct performance metrics, +many of which can have multiple values, for example, per disk, per CPU, +or per process.</para> +</section> +</section> +<section id="LE79836-PARENT"> + +<title>Conceptual Foundations</title> +<para><indexterm id="ITch01-129"><primary>conceptual foundations</primary> +</indexterm>The following sections provide a detailed overview of concepts +that underpin Performance Co-Pilot (PCP).</para> +<section id="id5188366"> + +<title>Performance Metrics</title> +<para><indexterm id="ITch01-130"><primary>PMAPI</primary><secondary>naming +metrics</secondary></indexterm><indexterm id="IG3137188863"><primary>performance metrics +</primary><secondary>concept</secondary></indexterm> Across all of the +supported performance metric domains, there are a large number of performance +metrics. Each metric has its own structure and semantics. PCP presents +a uniform interface to these metrics, independent of the underlying metric +data source.</para> +<para><indexterm id="IG3137188864"><primary>PMNS</primary><secondary>brief description</secondary> +</indexterm>The Performance Metrics Name Space (PMNS) provides a hierarchical +classification of human-readable metric names, and a mapping from these external +names to internal metric identifiers. See <xref linkend="LE94677-PARENT"/>, for +a description of the PMNS.</para> +</section> +<section id="id5188440"> + +<title>Performance Metric Instances</title> +<para>When performance metric values are returned to a requesting application, +there may be more than one value instance for a particular metric; for +example, independent counts for each CPU, process, disk, or local filesystem. +Internal instance identifiers correspond one to one with external (human-readable) +descriptions of the members of an instance domain.</para> +<para>Transient performance metrics (such as per-process information) +cause repeated requests for the same metric to return different numbers +of values, or changes in the particular instance identifiers returned. +These changes are expected and fully supported by the PCP infrastructure; +however, metric instantiation is guaranteed to be valid only at the time of collection.</para> +</section> +<section id="id5188469"> + +<title>Current Metric Context</title> +<para>When performance metrics are retrieved, they are delivered in the +context of a particular source of metrics, a point in time, and a profile +of desired instances. This means that the application making the request +has already negotiated to establish the context in which the request should +be executed.</para> +<para><indexterm id="IG3137188865"><primary>pmlogger tool</primary><secondary>current metric +context</secondary></indexterm>A metric source may be the current performance +data from a particular host (a live or real-time source), or an archive +log of performance data collected by <command>pmlogger</command> at some +distant host or at an earlier time (a retrospective or archive source). +</para> +<para><indexterm id="ITch01-134"><primary>collection time</primary></indexterm>By +default, the collection time for a performance metric is the current time +of day for real-time sources, or current point within an archive source. +For archives, the collection time may be reset to an arbitrary time within +the bounds of the archive log.<indexterm id="ITch01-135"><primary>archive logs</primary> +<secondary>collection time</secondary></indexterm></para> +</section> +<section id="id5188562"> + +<title>Sources of Performance Metrics and Their Domains</title> +<para><indexterm id="ITch01-137"><primary>performance metrics</primary> +<secondary>sources</secondary></indexterm><indexterm id="ITch01-138"> +<primary>functional domains</primary></indexterm> Instrumentation for +the purpose of performance monitoring typically consists of counts of +activity or events, attribution of resource consumption, and service-time +or response-time measures. This instrumentation may exist in one or more +of the functional domains as shown in <xref linkend="id5188602"/>. +</para> +<figure id="id5188602"><title>Performance Metric Domains as Autonomous Collections +of Data</title><mediaobject><imageobject><imagedata fileref="figures/metric-domains.svg"/></imageobject><textobject><phrase>Performance Metric Domains as Autonomous Collections +of Data</phrase></textobject></mediaobject></figure> +<para>Each domain has an associated access method:</para> +<itemizedlist> +<listitem><para><indexterm id="IG3137188866"><primary>Kernel data structures</primary></indexterm>The +operating system kernel, including sub-system data structures - per-process +resource consumption, network statistics, disk activity, or memory management +instrumentation.</para> +</listitem> +<listitem><para><indexterm id="IG3137188867"><primary>Mail servers</primary></indexterm><indexterm id="IG3137188868"> +<primary>layered software services</primary></indexterm>A layered software +service such as activity logs for a World Wide Web server or an email delivery +server.<indexterm id="IG3137188869"><primary>application programs</primary></indexterm></para> +</listitem> +<listitem><para>An application program such as measured response time +for a production application running a periodic and benign probe transaction +(as often required in service level agreements), or rate of computation +and throughput in jobs per minute for a batch stream.</para> +</listitem> +<listitem><para><indexterm id="IG3137188870"><primary>network routers and bridges</primary> +</indexterm><indexterm id="IG3137188871"><primary>external equipment</primary></indexterm>External +equipment such as network routers and bridges.</para> +</listitem></itemizedlist> +<para><indexterm id="ITch01-139"><primary>performance metrics</primary> +<secondary>methods</secondary></indexterm>For each domain, the set of +performance metrics may be viewed as an abstract data type, with an associated +set of methods that may be used to perform the following tasks:</para> +<itemizedlist> +<listitem><para>Interrogate the metadata that describes the syntax and +semantics of the performance metrics</para> +</listitem> +<listitem><para>Control (enable or disable) the collection of some or +all of the metrics</para> +</listitem> +<listitem><para>Extract instantiations (current values) for some or all +of the metrics</para> +</listitem></itemizedlist> +<para>We refer to each functional domain as a performance metrics domain +and assume that domains are functionally, architecturally, and administratively +independent and autonomous. Obviously the set of performance metrics domains +available on any host is variable, and changes with time as software and +hardware are installed and removed.</para> +<para>The number of performance metrics domains may be further enlarged +in cluster-based or network-based configurations, where there is potentially +an instance of each performance metrics domain on each node. Hence, the +management of performance metrics domains must be both extensible at a +particular host and distributed across a number of hosts.</para> +<para><indexterm id="IG3137188872"><primary>PMID</primary><secondary>description</secondary> +</indexterm><indexterm id="IG3137188873"><primary>Performance Metric Identifier</primary> +<see>PMID</see></indexterm>Each performance metrics domain on a particular +host must be assigned a unique Performance Metric Identifier (PMID). In +practice, this means unique identifiers are assigned globally for each +performance metrics domain type. For example, the same identifier would +be used for the Apache Web Server performance metrics domain on all hosts.</para> +</section> +<section id="id5188837"> + +<title>Distributed Collection</title> +<para><indexterm id="ITch01-142"><primary>distributed collection</primary> +</indexterm><indexterm id="ITch01-143"><primary>collector hosts</primary> +</indexterm><indexterm id="IG3137188874"><primary>PMCD</primary><secondary>distributed collection +</secondary></indexterm>The performance metrics collection architecture +is distributed, in the sense that any performance tool may be executing +remotely. However, a PMDA usually runs on the system for which it is collecting +performance measurements. In most cases, connecting these tools together +on the collector host is the responsibility of the PMCD process, as shown +in <xref linkend="id5188883"/>.</para> +<figure id="id5188883"><title>Process Structure for Distributed Operation</title> +<mediaobject><imageobject><imagedata fileref="figures/remote-collector.svg"/></imageobject><textobject><phrase>Process Structure for Distributed Operation</phrase></textobject></mediaobject></figure> +<para>The host running the monitoring tools does not require any collection +tools, including <command>pmcd</command>, because all requests for metrics +are sent to the <command>pmcd</command> process on the collector host. +These requests are then forwarded to the appropriate PMDAs, which respond +with metric descriptions, help text, and most importantly, metric values. +</para> +<para><indexterm id="IG3137188875"><primary>PMCD</primary><secondary>distributed collection +</secondary></indexterm>The connections between monitor clients and <literal>pmcd</literal> processes are managed in <filename>libpcp</filename>, below +the PMAPI level; see the <command>pmapi(3)</command> man page. +Connections between PMDAs and <command>pmcd</command> are managed by the +PMDA routines; see the <command>pmda(3)</command> man page. +There can be multiple monitor clients and multiple PMDAs on the one host, +but normally there would be only one <literal>pmcd</literal> process.</para> +</section> +<section id="LE94677-PARENT"> + +<title>Performance Metrics Name Space</title> +<para><indexterm id="ITch01-144"><primary>PMNS</primary><secondary>description +</secondary></indexterm> <indexterm id="ITch01-146"><primary>PMID</primary> +<secondary>description</secondary></indexterm>Internally, each unique +performance metric is identified by a Performance Metric Identifier (PMID) +drawn from a universal set of identifiers, including some that are reserved +for site-specific, application-specific, and customer-specific use.</para> +<para><indexterm id="ITch01-148"><primary>performance metrics</primary> +<secondary>PMNS</secondary></indexterm>An external name space - the Performance +Metrics Name Space (PMNS) - maps from a hierarchy (or tree) of human-readable +names to PMIDs.</para> +<section id="id5189100"> + +<title>Performance Metrics Name Space Diagram</title> +<para>Each node in the PMNS tree is assigned a label that must begin with +an alphabet character, and be followed by zero or more alphanumeric characters +or the underscore (_) character. The root node of the tree has the special +label of <literal>root</literal>.</para> +<para>A metric name is formed by traversing the tree from the root to +a leaf node with each node label on the path separated by a period. The +common prefix <literal>root</literal><emphasis role="bold">.</emphasis> is omitted +from all names. For example, <xref linkend="id5189137"/> shows the +nodes in a small subsection of a PMNS.</para> +<figure id="id5189137"><title>Small Performance Metrics Name Space (PMNS) +</title><mediaobject><imageobject><imagedata fileref="figures/pmns-small.svg"/></imageobject><textobject><phrase>Small Performance Metrics Name Space (PMNS) +</phrase></textobject></mediaobject></figure> +<para>In this subsection, the following are valid names for performance +metrics:</para> +<literallayout class="monospaced">kernel.percpu.syscall +network.tcp.rcvpack +hw.router.recv.total_util +</literallayout> +</section> +</section> +<section id="id5189172"> + +<title>Descriptions for Performance Metrics</title> +<para><indexterm id="ITch01-149"><primary>performance metrics</primary> +<secondary>descriptions</secondary></indexterm><indexterm id="ITch01-150"> +<primary>metadata</primary></indexterm> Through the various performance +metric domains, the PCP must support a wide range of formats and semantics +for performance metrics. This <firstterm>metadata</firstterm> describing +the performance metrics includes the following:</para> +<itemizedlist> +<listitem><para>The internal identifier, Performance Metric Identifier +(PMID), for the metric</para> +</listitem> +<listitem><para><indexterm id="IG3137188876"><primary>64-bit IEEE format</primary></indexterm>The +format and encoding for the values of the metric, for example, an unsigned +32-bit integer or a string or a 64-bit IEEE format floating point number +</para> +</listitem> +<listitem><para>The semantics of the metric, particularly the interpretation +of the values as free-running counters or instantaneous values</para> +</listitem> +<listitem><para>The dimensionality of the values, in the dimensions of +events, space, and time</para> +</listitem> +<listitem><para>The scale of values; for example, bytes, kilobytes (KB), +or megabytes (MB) for the space dimension</para> +</listitem> +<listitem><para>An indication if the metric may have one or many associated +values</para> +</listitem> +<listitem><para>Short (and extended) help text describing the metric</para> +</listitem></itemizedlist> +<para>For each metric, this metadata is defined within the associated +PMDA, and PCP arranges for the information to be exported to performance +tools that use the metadata when interpreting the values for each metric.</para> +</section> +<section id="id5189302"> + +<title>Values for Performance Metrics</title> +<para>The following sections describe two types of performance metrics, +single-valued and set-valued.</para> +<section id="id5189314"> + +<title>Single-Valued Performance Metrics</title> +<para><indexterm id="IG3137188877"><primary>single-valued performance metrics</primary> +</indexterm>Some performance metrics have a singular value within their +performance metric domains. For example, available memory (or the total +number of context switches) has only one value per performance metric +domain, that is, one value per host. The metadata describing the metric +makes this fact known to applications that process values for these metrics. +</para> +</section> +<section id="id5189346"> + +<title>Set-Valued Performance Metrics</title> +<para><indexterm id="IG3137188878"><primary>set-valued performance metrics</primary></indexterm>Some +performance metrics have a set of values or instances in each implementing +performance metric domain. For example, one value for each disk, one value +for each process, one value for each CPU, or one value for each activation +of a given application.</para> +<para>When a metric has multiple instances, the PCP framework does not +pollute the Name Space with additional metric names; rather, a single +metric may have an associated set of values. These multiple values are +associated with the members of an <firstterm>instance domain</firstterm>, +such that each instance has a unique instance identifier within the associated +instance domain. For example, the “per CPU” instance domain +may use the instance identifiers 0, 1, 2, 3, and so on to identify the +configured processors in the system.</para> +<para>Internally, instance identifiers are encoded as binary values, but +each performance metric domain also supports corresponding strings as +external names for the instance identifiers, and these names are used +at the user interface to the PCP utilities.</para> +<para>For example, the performance metric <literal>disk.dev.total</literal> +counts I/O operations for each disk spindle, and the associated instance +domain contains one member for each disk spindle. On a system with five +specific disks, one value would be associated with each of the external +and internal instance identifier pairs shown in <xref linkend="id5189432"/>. +</para> +<table id="id5189432" frame="topbot"> + +<title>Sample Instance Identifiers for Disk Statistics +</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="198*"/> +<colspec colwidth="198*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>External Instance +Identifier</para></entry><entry align="left" valign="bottom"><para>Internal +Instance Identifier</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para>disk0</para></entry> +<entry align="left" valign="top"><para>131329</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>disk1</para></entry> +<entry align="left" valign="top"><para>131330</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>disk2</para></entry> +<entry align="left" valign="top"><para>131331</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>disk3</para></entry> +<entry align="left" valign="top"><para>131841</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>disk4</para></entry> +<entry align="left" valign="top"><para>131842</para></entry></row></tbody> +</tgroup></table> +<para>Multiple performance metrics may be associated with a single instance +domain.</para> +<para>Each performance metric domain may dynamically establish the instances +within an instance domain. For example, there may be one instance for +the metric <literal>kernel.percpu.idle</literal> on a workstation, but +multiple instances on a multiprocessor server. Even more dynamic is <literal>filesys.free</literal>, where the values report the amount of free space +per file system, and the number of values tracks the mounting and unmounting +of local filesystems.</para> +<para>PCP arranges for information describing instance domains to be exported +from the performance metric domains to the applications that require this +information. Applications may also choose to retrieve values for all instances +of a performance metric, or some arbitrary subset of the available instances. +</para> +</section> +</section> +<section id="id5189653"> + +<title>Collector and Monitor Roles</title> +<para><indexterm id="ITch01-155"><primary>roles</primary><secondary>collector +</secondary></indexterm><indexterm id="IG3137188879"><primary>roles</primary><secondary> +monitor</secondary></indexterm>Hosts supporting PCP services are broadly +classified into two categories:</para> +<variablelist id="Z926617459sdc"> +<varlistentry> +<term>Collector</term> +<listitem><para><indexterm id="ITch01-156"><primary>collector hosts</primary> +</indexterm><indexterm id="IG3137188880"><primary>PMDA</primary><secondary>collectors</secondary> +</indexterm>Hosts that have <literal>pmcd</literal> and one or more performance +metric domain agents (PMDAs) running to collect and export performance +metrics</para> +</listitem></varlistentry> +<varlistentry> +<term>Monitor</term> +<listitem><para><indexterm id="IG3137188881"><primary>monitor hosts</primary></indexterm>Hosts +that import performance metrics from one or more collector hosts to be +consumed by tools to monitor, manage, or record the performance of the +collector hosts</para> +</listitem></varlistentry> +</variablelist> +<para>Each PCP enabled host can operate as a collector, a monitor, or +both.</para> +</section> +<section id="id5189901"> + +<title>Retrospective Sources of Performance Metrics</title> +<para><indexterm id="ITch01-159"><primary>performance metrics</primary> +<secondary>retrospective sources</secondary></indexterm>The PMAPI also +supports delivery of performance metrics from a historical +source in the form of a PCP archive log. Archive logs are created using +the <literal>pmlogger</literal> utility, and are replayed in an architecture +as shown in <xref linkend="id5189940"/>.</para> +<figure id="id5189940"><title>Architecture for Retrospective Analysis</title><mediaobject><imageobject><imagedata fileref="figures/retrospective-architecture.svg"/></imageobject><textobject><phrase>Architecture for Retrospective Analysis</phrase></textobject></mediaobject></figure> +<para>The PMAPI has been designed to minimize the differences required +for an application to process performance data from an archive or from +a real-time source. As a result, most PCP tools support live and retrospective +monitoring with equal facility.</para> +</section> +<section id="id5189964"> + +<title>Product Extensibility</title> +<para><indexterm id="ITch01-160"><primary>PCP</primary><secondary>extensibility +</secondary></indexterm>Much of the PCP software's potential for attacking +difficult performance problems in production environments comes from the +design philosophy that considers extensibility to be critically important. +</para> +<para>The performance analyst can take advantage of the PCP infrastructure +to deploy value-added performance monitoring tools and services. Here +are some examples:</para> +<itemizedlist> +<listitem><para>Easy extension of the PCP collector to accommodate new +performance metrics and new sources of performance metrics, in particular +using the interfaces of a special-purpose library to develop new PMDAs +(see the <command>pmda(3)</command> man page)</para> +</listitem> +<listitem><para><indexterm id="IG3137188885"><primary>libpcp_pmda library</primary></indexterm><indexterm id="IG3137188886"> +<primary>libpcp_mmv library</primary></indexterm>Use of libraries +(<filename>libpcp_pmda</filename> and <filename>libpcp_mmv</filename>) +to aid in the development of new capabilities to export performance metrics +from local applications</para> +</listitem> +<listitem><para>Operation on any performance metric using generalized +toolkits</para> +</listitem> +<listitem><para>Distribution of PCP components such as collectors across +the network, placing the service where it can do the most good</para> +</listitem> +<listitem><para>Dynamic adjustment to changes in system configuration +</para> +</listitem> +<listitem><para>Flexible customization built into the design of all PCP +tools</para> +</listitem> +<listitem><para>Creation of new monitor applications, using the routines +described in the <command>pmapi(3)</command> man page</para> +</listitem></itemizedlist> +</section> +</section> +<section id="LE13618-PARENT"> + +<title>Overview of Component Software</title> +<para><indexterm id="IG3137188825"><primary>software</primary></indexterm><indexterm id="IG3137188826"><primary> +component software</primary></indexterm>Performance Co-Pilot (PCP) is +composed of both text-based and graphical tools. Each tool is fully +documented by a man page. These man pages are named after the +tools or commands they describe, and are accessible through the <command>man</command> +command. For example, to see the <command>pminfo(1)</command> man page for the +<command>pminfo</command> command, enter this command:</para> +<literallayout class="monospaced"><userinput>man pminfo</userinput></literallayout> +<para>A representative list of PCP tools and commands, grouped by functionality, +is provided in the following four sections.</para> +<section id="id5177430"> + +<title>Performance Monitoring and Visualization</title> +<para><indexterm id="IG3137188827"><primary>PCP</primary><secondary>tool summaries</secondary> +</indexterm><indexterm id="IG3137188828"><primary>performance monitoring</primary></indexterm>The +following tools provide the principal services for the PCP end-user with +an interest in monitoring, visualizing, or processing performance information +collected either in real time or from PCP archive logs:</para> +<variablelist> +<varlistentry> +<term><command>pmatop</command></term> +<listitem><para><indexterm id="IG3137188800"><primary>pmatop tool</primary> +<secondary>brief description</secondary></indexterm>Full-screen monitor +of the load on a system from a kernel, hardware and processes point of view. +It is modeled on the Linux <command>atop(1)</command> tool +(<ulink url="http://www.atoptool.nl/">home page</ulink>) and provides a +showcase for the variety of data available using PCP services and the +Python scripting interfaces.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmchart</command></term> +<listitem><para><indexterm id="IG3137188800nat"><primary>pmchart tool</primary> +<secondary>brief description</secondary></indexterm>Strip chart tool for +arbitrary performance metrics. Interactive graphical utility that can display +multiple charts simultaneously, from multiple hosts or archives, aligned on a +unified time axis (X-axis), or on multiple tabs.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmcollectl</command></term> +<listitem><para><indexterm id="IG3137188801"><primary>pmcollectl tool</primary> +<secondary>brief description</secondary></indexterm>Statistics collection +tool with good coverage of a number of Linux kernel subsystems, with the +everything-in-one-tool approach pioneered by <command>sar(1)</command>. +It is modeled on the Linux <command>collectl(1)</command> utility +(<ulink url="http://collectl.sourceforge.net/">home page</ulink>) and +provides another example of use of the Python scripting interfaces to build +more complex functionality with relative ease, with PCP as a foundation.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdumptext</command></term> +<listitem><para><indexterm id="ITch01-22"><primary>pmdumptext tool</primary> +<secondary>brief description</secondary></indexterm>Outputs the values +of arbitrary performance metrics collected live or from a PCP archive, in +textual format.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmevent</command></term> +<listitem><para><indexterm id="IG3137188713"><primary>pmevent tool</primary> +<secondary>brief description</secondary></indexterm>Reports on event metrics, +decoding the timestamp and event parameters for text-based reporting.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmie</command></term> +<listitem><para><indexterm id="ITch01-32"><primary>pmie tool</primary> +<secondary>brief description</secondary></indexterm>Evaluates predicate-action +rules over performance metrics for alarms, automated system management tasks, +dynamic configuration tuning, and so on. It is an inference engine.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmieconf</command></term> +<listitem><para><indexterm id="IG3137188829"><primary>pmieconf tool</primary><secondary> +brief description</secondary></indexterm><indexterm id="IG3137188830"><primary>pmie tool +</primary><secondary>pmieconf rules</secondary></indexterm>Creates parameterized +rules to be used with the PCP inference engine (<command>pmie</command>). +It can be run either interactively or from scripts for automating the setup of inference +(the PCP start scripts do this, for example, to generate a default configuration).</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pminfo</command></term> +<listitem><para><indexterm id="ITch01-34"><primary>pminfo tool</primary> +<secondary>brief description</secondary></indexterm>Displays information +about arbitrary performance metrics available from PCP, including help +text with <literal>-T</literal>.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmlogsummary</command></term> +<listitem><para><indexterm id="IG3137188831"><primary>pmlogsummary tool</primary></indexterm>Calculates +and reports various statistical summaries of the performance metric values +from a PCP archive.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmprobe</command></term> +<listitem><para><indexterm id="IG3137188832"><primary>pmprobe tool</primary></indexterm>Probes +for performance metric availability, values, and instances.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmstat</command></term> +<listitem><para><indexterm id="ITch01-37"><primary>pmstat tool</primary> +<secondary>brief description</secondary></indexterm>Provides a text-based +display of metrics that summarize the performance of one or more systems +at a high level.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmval</command></term> +<listitem><para><indexterm id="ITch01-42"><primary>pmval tool</primary> +<secondary>brief description</secondary></indexterm>Provides a text-based +display of the values for arbitrary instances of a selected performance +metric, suitable for ASCII logs or inquiry over a slow link.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5177776"> + +<title>Collecting, Transporting, and Archiving Performance Information +</title> +<para><indexterm id="IG3137188833"><primary>PCP</primary><secondary>tool summaries</secondary> +</indexterm><indexterm id="IG3137188834"><primary>data collection tools</primary></indexterm><indexterm id="IG3137188835"> +<primary>network transportation tools </primary></indexterm><indexterm id="IG3137188836"> +<primary>archive logs</primary><secondary>creation</secondary></indexterm>PCP +provides the following tools to support real-time data collection, network +transport, and archive log creation services for performance data:</para> +<variablelist> +<varlistentry> +<term><command>mkaf</command></term> +<listitem><para><indexterm id="ITch01-48"><primary>mkaf tool</primary> +</indexterm>Aggregates an arbitrary collection of PCP archive logs into +a <firstterm>folio</firstterm> to be used with <command>pmafm</command>. +</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmafm</command></term> +<listitem><para><indexterm id="ITch01-50"><primary>pmafm tool</primary> +<secondary>brief description</secondary></indexterm>Interrogates, manages, +and replays an archive folio as created by <command>mkaf</command>, or +the periodic archive log management scripts, or the record mode of other +PCP tools.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmcd</command></term> +<listitem><para><indexterm id="ITch01-52"><primary>PMCD</primary><secondary> +brief description</secondary></indexterm><indexterm id="IG3137188837"><primary>Performance +Metrics Collection Daemon</primary><see>PMCD</see></indexterm><indexterm id="IG3137188838"> +<primary>pmcd tool</primary><see>PMCD</see></indexterm>Is the Performance +Metrics Collection Daemon (PMCD). This daemon must run on each system +being monitored, to collect and export the performance information necessary +to monitor the system.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmcd_wait</command></term> +<listitem><para><indexterm id="IG3137188839"><primary>pmcd_wait tool</primary></indexterm>Waits +for <command>pmcd</command> to be ready to accept client connections. +</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdaapache</command></term> +<listitem><para><indexterm id="IG3137188803"><primary>pmdaapache tool</primary> +</indexterm>Exports performance metrics from the Apache Web Server. +It is a Performance Metrics Domain Agent (PMDA).</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdacisco</command></term> +<listitem><para><indexterm id="ITch01-54"><primary>pmdacisco tool</primary> +</indexterm>Extracts performance metrics from one or more Cisco routers.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdaelasticseach</command></term> +<listitem><para><indexterm id="IG3137188714"><primary>pmdaelasticsearch tool</primary> +</indexterm>Extracts performance metrics from an elasticsearch cluster.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdagfs2</command></term> +<listitem><para><indexterm id="IG3137188804"><primary>pmdagfs2 tool</primary> +</indexterm>Exports performance metrics from the GFS2 clustered filesystem.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdagluster</command></term> +<listitem><para><indexterm id="IG3137188712"><primary>pmdagluster tool</primary> +</indexterm>Extracts performance metrics from the Gluster filesystem.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdainfiniband</command></term> +<listitem><para><indexterm id="IG3137188805"><primary>pmdainfiniband tool</primary> +</indexterm>Exports performance metrics from the Infiniband kernel driver.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdakvm</command></term> +<listitem><para><indexterm id="IG3137188806"><primary>pmdakvm tool</primary> +</indexterm>Extracts performance metrics from the Linux Kernel Virtual Machine (KVM) +infrastructure.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdalustrecomm</command></term> +<listitem><para><indexterm id="IG3137188807"><primary>pmdalustrecomm tool</primary> +</indexterm>Exports performance metrics from the Lustre clustered filesystem.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdamailq</command></term> +<listitem><para><indexterm id="ITch01-58"><primary>pmdamailq tool</primary> +</indexterm>Exports performance metrics describing the current state of +items in the <literal>sendmail</literal> queue.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdamemcache</command></term> +<listitem><para><indexterm id="IG3137188808"><primary>pmdamemcache tool</primary> +</indexterm>Extracts performance metrics from memcached, a distributed +memory caching daemon commonly used to improve web serving performance.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdammv</command></term> +<listitem><indexterm id="IG3137188841"><primary>pmdammv tool</primary></indexterm><para> +Exports metrics from instrumented applications linked with the <filename>pcp_mmv</filename> +shared library or the +<ulink url="http://code.google.com/p/parfait/">Parfait</ulink> +framework for Java instrumentation. +These metrics are custom developed per application, and in the case of Parfait, automatically +include numerous JVM, Tomcat and other server or container statistics.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdamysql</command></term> +<listitem><para><indexterm id="IG3137188809"><primary>pmdamysql tool</primary> +</indexterm>Extracts performance metrics from the MySQL relational database.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdanamed</command></term> +<listitem><para><indexterm id="IG3137188701"><primary>pmdanamed tool</primary> +</indexterm>Exports performance metrics from the Internet domain name server, named.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdanginx</command></term> +<listitem><para><indexterm id="IG3137188702"><primary>pmdanginx tool</primary> +</indexterm>Extracts performance metrics from the nginx HTTP and reverse proxy server.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdapostfix</command></term> +<listitem><para><indexterm id="IG3137188703"><primary>pmdapostfix tool</primary> +</indexterm>Export performance metrics from the Postfix mail transfer agent.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdapostgres</command></term> +<listitem><para><indexterm id="IG3137188704"><primary>pmdapostgres tool</primary> +</indexterm>Extracts performance metrics from the PostgreSQL relational database.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdaproc</command></term> +<listitem><para><indexterm id="IG3137188705"><primary>pmdaproc tool</primary> +</indexterm>Exports performance metrics for running processes.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdarsyslog</command></term> +<listitem><para><indexterm id="IG3137188706"><primary>pmdarsyslog tool</primary> +</indexterm>Extracts performance metrics from the Reliable System Log daemon.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdasamba</command></term> +<listitem><para><indexterm id="IG3137188707"><primary>pmdasamba tool</primary> +</indexterm>Extracts performance metrics from Samba, a Windows SMB/CIFS server.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdasendmail</command></term> +<listitem><para><indexterm id="IG3137188842"><primary>pmdasendmail tool</primary></indexterm>Exports +mail activity statistics from <command>sendmail</command>. +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmdashping</literal></term> +<listitem><para><indexterm id="ITch01-60"><primary>pmdashping tool</primary> +</indexterm>Exports performance metrics for the availability and quality +of service (response-time) for arbitrary shell commands. +</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdasnmp</command></term> +<listitem><para><indexterm id="IG3137188708"><primary>pmdasnmp tool</primary> +</indexterm>Extracts SNMP performance metrics from local or remote SNMP-enabled devices.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdasummary</command></term> +<listitem><para><indexterm id="ITch01-62"><primary>pmdasummary tool</primary> +</indexterm>Derives performance metrics values from values made available +by other PMDAs. It is a PMDA itself.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdasystemd</command></term> +<listitem><para><indexterm id="IG3137188709"><primary>pmdasystemd tool</primary> +</indexterm>Extracts performance metrics from the systemd and journald services.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmdatrace</literal></term> +<listitem><para><indexterm id="ITch01-64"><primary>pmdatrace tool</primary> +</indexterm>Exports transaction performance metrics from application processes +that use the <filename>pcp_trace</filename> library.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdavmware</command></term> +<listitem><para><indexterm id="IG3137188710"><primary>pmdavmware tool</primary> +</indexterm>Extracts performance metrics from a VMWare virtualization host.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdaweblog</command></term> +<listitem><indexterm id="IG3137188843"><primary>pmdaweblog tool</primary></indexterm><para> +Scans Web-server logs to extract metrics characterizing.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdaxfs</command></term> +<listitem><para><indexterm id="IG3137188711"><primary>pmdaxfs tool</primary> +</indexterm>Extracts performance metrics from the Linux kernel XFS filesystem implementation.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdumplog</command></term> +<listitem><para><indexterm id="ITch01-66"><primary>pmdumplog tool</primary> +<secondary>brief description</secondary></indexterm>Displays selected +state information, control data, and metric values from a PCP archive +log created by <command>pmlogger</command>.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmlc</command></term> +<listitem><para><indexterm id="ITch01-68"><primary>pmlc tool</primary> +<secondary>brief description</secondary></indexterm>Exercises control +over an instance of the PCP archive logger <command>pmlogger</command>, +to modify the profile of which metrics are logged and/or how frequently +their values are logged.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmlogcheck</command></term> +<listitem><para><indexterm id="IG3137188844"><primary>pmlogcheck tool</primary></indexterm>Performs +integrity check for PCP archives.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmlogconf</command></term> +<listitem><para><indexterm id="IG3137188845"><primary>pmlogconf tool</primary></indexterm>Creates +or modifies <command>pmlogger</command> configuration files for many common +logging scenarios, optionally probing for available metrics and enabled functionality. +It can be run either interactively or from scripts for automating the setup of data logging +(the PCP start scripts do this, for example, to generate a default configuration).</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmlogextract</command></term> +<listitem><para><indexterm id="ITch01-72"><primary>pmlogextract tool</primary> +</indexterm>Reads one or more PCP archive logs and creates a temporally +merged and reduced PCP archive log as output.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmlogger</command></term> +<listitem><para><indexterm id="IG3137188846"><primary>pmlogger tool</primary><secondary> +brief description</secondary></indexterm>Creates PCP archive logs of performance +metrics over time. Many tools accept these PCP archive logs as alternative +sources of metrics for retrospective analysis.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmproxy</command></term> +<listitem><para><indexterm id="ITch01-38"><primary>pmproxy tool</primary> +<secondary>brief description</secondary></indexterm>Allows the execution +of PCP tools through a network firewall system.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmtrace</command></term> +<listitem><para><indexterm id="ITch01-74"><primary>pmtrace tool</primary> +</indexterm>Provides a simple command line interface to the trace PMDA +and its associated <filename>pcp_trace</filename> library.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmwebd</command></term> +<listitem><para><indexterm id="IG3137188802"><primary>web daemon</primary> +</indexterm>Is the Performance Metrics Web Daemon, a front-end to both +<command>pmcd</command> and PCP archives, +providing a JSON interface suitable for use by web-based tools wishing to +access performance data over HTTP.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5187554"> + +<title>Operational and Infrastructure Support</title> +<para><indexterm id="IG3137188847"><primary>PCP</primary><secondary>tool summaries</secondary> +</indexterm><indexterm id="IG3137188848"><primary>operational support tools</primary></indexterm><indexterm id="ITch01-76"><primary>infrastructure support tools</primary></indexterm>PCP +provides the following tools to support the PCP infrastructure and assist +operational procedures for PCP deployment in a production environment: +</para> +<variablelist> +<varlistentry> +<term><command>pcp</command></term> +<listitem><para><indexterm id="IG3137188850"><primary>pcp tool</primary></indexterm>Summarizes +that state of a PCP installation.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmdbg</command></term> +<listitem><para><indexterm id="ITch01-89"><primary>pmdbg facility</primary> +</indexterm><indexterm id="IG3137188851"><primary>diagnostic tools</primary></indexterm><indexterm id="ITch01-90"><primary>debugging tools</primary></indexterm>Describes +the available facilities and associated control flags. PCP tools include +internal diagnostic and debugging facilities that may be activated by +run-time flags.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmerr</command></term> +<listitem><para><indexterm id="ITch01-91"><primary>pmerr tool</primary> +</indexterm>Translates PCP error codes into human-readable error messages. +</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmhostname</command></term> +<listitem><para><indexterm id="IG3137188852"><primary>pmhostname tool</primary></indexterm>Reports +hostname as returned by <command>gethostbyname</command>. Used in assorted +PCP management scripts.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmie_check</command></term> +<listitem><para><indexterm id="IG3137188853"><primary>pmie tool</primary><secondary>brief +description</secondary></indexterm>Administration of the Performance Co-Pilot +inference engine (<command>pmie</command>).</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmlock</command></term> +<listitem><para><indexterm id="ITch01-95"><primary>pmlock tool</primary> +</indexterm>Attempts to acquire an exclusive lock by creating a file with +a mode of 0.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmlogger_*</command></term> +<listitem><para><indexterm id="IG3137188854"><primary>pmlogger_check script</primary></indexterm><indexterm id="IG3137188855"> +<primary>pmlogger_daily script</primary></indexterm><indexterm id="IG3137188856"><primary> +pmlogger_merge script</primary></indexterm><indexterm id="IG3137188857"><primary>pmsnap +tool</primary><secondary>brief description</secondary></indexterm><indexterm id="IG3137188858"> +<primary>scripts</primary></indexterm>Allows you to create a customized +regime of administration and management for PCP archive log files. The <literal>pmlogger_check</literal>, <literal>pmlogger_daily</literal>, and <literal>pmlogger_merge</literal> scripts are intended for periodic execution via +the <command>cron</command> command.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmnewlog</command></term> +<listitem><para><indexterm id="ITch01-100"><primary>pmnewlog tool</primary> +</indexterm>Performs archive log rotation by stopping and restarting an +instance of <command>pmlogger</command>.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmnsadd</command></term> +<listitem><para><indexterm id="ITch01-102"><primary>pmnsadd tool</primary> +</indexterm>Adds a subtree of new names into a PMNS, as used by the components +of PCP.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmnsdel</command></term> +<listitem><para><indexterm id="ITch01-106"><primary>pmnsdel tool</primary> +</indexterm>Removes a subtree of names from a PMNS, as used by the components +of the PCP.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmnsmerge</command></term> +<listitem><para><indexterm id="IG3137188859"><primary>pcp tool</primary></indexterm>Merges +multiple PMNS files together, as used by the components of PCP.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmstore</command></term> +<listitem><para><indexterm id="ITch01-112"><primary>pmstore tool</primary> +<secondary>brief description</secondary></indexterm>Reinitializes counters +or assigns new values to metrics that act as control variables. The command +changes the current values for the specified instances of a single performance +metric.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5188066"> + +<title>Application and Agent Development</title> +<para><indexterm id="ITch01-114"><primary>application programs</primary> +</indexterm><indexterm id="IG3137188860"><primary>PCP</primary><secondary>tool summaries +</secondary></indexterm>The following PCP tools aid the development of +new programs to consume performance data, and new agents to export performance +data within the PCP framework:</para> +<variablelist> +<varlistentry> +<term><command>chkhelp</command></term> +<listitem><para><indexterm id="ITch01-115"><primary>chkhelp tool</primary> +</indexterm>Checks the consistency of performance metrics help database +files.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>dbpmda</command></term> +<listitem><para><indexterm id="ITch01-117"><primary>dbpmda tool</primary> +</indexterm>Allows PMDA behavior to be exercised and tested. It is an +interactive debugger for PMDAs.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>newhelp</command></term> +<listitem><para><indexterm id="ITch01-119"><primary>newhelp tool</primary> +</indexterm>Generates the database files for one or more source files +of PCP help text.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmapi</command></term> +<listitem><para><indexterm id="ITch01-121"><primary>pmclient tool</primary> +</indexterm><indexterm id="IG3137188861"><primary>PMAPI</primary><secondary>brief description +</secondary></indexterm><indexterm id="IG3137188862"><primary>Performance Metrics Application +Programming Interface </primary><see>PMAPI</see></indexterm>Defines a +procedural interface for developing PCP client applications. It is the +Performance Metrics Application Programming Interface (PMAPI).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmclient</literal></term> +<listitem><para><indexterm id="ITch01-123"><primary>pmclient tool</primary> +</indexterm>Is a simple client that uses the PMAPI to report some high-level +system performance metrics. </para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmda</command></term> +<listitem><para><indexterm id="ITch01-127"><primary>dbpmda tool</primary> +<see>PMDA</see></indexterm>Is a library used by many shipped PMDAs to +communicate with a <command>pmcd</command> process. It can expedite the +development of new and custom PMDAs.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmgenmap</command></term> +<listitem><para><indexterm id="ITch01-125"><primary>pmgenmap tool</primary> +</indexterm>Generates C declarations and <command>cpp(1)</command> macros +to aid the development of customized programs that use the facilities +of PCP. It is a PMDA development tool.</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +</chapter> + + + +<chapter id="LE17127-PARENT"> + +<title>Installing and Configuring Performance Co-Pilot</title> +<para><indexterm id="ITch02-0"><primary>installing PCP</primary></indexterm><indexterm id="ITch02-1"><primary>configuring PCP</primary></indexterm><indexterm id="ITch02-3"> +<primary>PCP</primary><secondary>configuring and installing</secondary></indexterm>The +sections in this chapter describe the basic installation and configuration +steps necessary to run Performance Co-Pilot (PCP) on your systems. The following +major sections are included:</para> +<itemizedlist> +<listitem><para><xref linkend="LE18649-PARENT"/> describes the main packages +of PCP software and how they must be installed on each system.</para> +</listitem> +<listitem><para><xref linkend="LE26146-PARENT"/>, describes the fundamentals +of maintaining the performance data collector.</para> +</listitem><listitem><para><xref linkend="LE43202-PARENT"/>, describes +the basics of installing a new Performance Metrics Domain Agent (PMDA) to +collect metric data and pass it to the PMCD.</para> +</listitem> +<listitem><para><xref linkend="LE70712-PARENT"/>, offers advice on problems +involving the PMCD.</para> +</listitem></itemizedlist> +<section id="LE18649-PARENT"> + +<title>Product Structure</title> +<para><indexterm id="IG3137188887"><primary>subsystems</primary></indexterm><indexterm id="ITch02-5"> +<primary>monitor configuration</primary></indexterm><indexterm id="IG3137188888"><primary>roles +</primary><secondary>collector</secondary></indexterm><indexterm id="IG3137188889"><primary> +roles</primary><secondary>monitor</secondary></indexterm>In a typical deployment, +Performance Co-Pilot (PCP) would be installed in a collector configuration +on one or more hosts, from which the performance information could then be +collected, and in a monitor configuration on one or more workstations, from +which the performance of the server systems could then be monitored.</para> +<para>On some platforms Performance Co-Pilot is presented as multiple packages; +typically separating the server components from graphical user interfaces and +documentation.</para> +<variablelist id="Z926620168sdc"> +<varlistentry> +<term>pcp-X.Y.Z-<replaceable>rev</replaceable></term> +<listitem><para>package for core PCP</para> +</listitem></varlistentry> +<varlistentry> +<term>pcp-gui-X.Y.Z-<replaceable>rev</replaceable></term> +<listitem><para>package for graphical PCP client tools</para> +</listitem></varlistentry> +<varlistentry> +<term>pcp-doc-X.Y.Z-<replaceable>rev</replaceable></term> +<listitem><para>package for online PCP documentation</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="LE26146-PARENT"> + +<title>Performance Metrics Collection Daemon (PMCD)</title> +<para><indexterm id="ITch02-20"><primary>PMCD</primary><secondary>maintenance +</secondary></indexterm><indexterm id="IG3137188890"><primary>Performance Metrics Collection +Daemon</primary><see>PMCD</see></indexterm> On each Performance Co-Pilot (PCP) +collection system, you must be certain that the <command>pmcd</command> daemon +is running. This daemon coordinates the gathering and exporting of performance +statistics in response to requests from the PCP monitoring tools.</para> +<section id="id5190406"> + +<title>Starting and Stopping the PMCD</title> +<para><indexterm id="IG3137188891"><primary>PMCD</primary><secondary>starting and stopping</secondary> +</indexterm>To start the daemon, enter the following commands as <literal>root</literal> on each PCP collection system:</para> +<literallayout class="monospaced"><userinput>chkconfig pmcd on</userinput>  +<userinput>${PCP_RC_DIR}/pmcd start</userinput> </literallayout> +<para>These commands instruct the system to start the daemon immediately, +and again whenever the system is booted. It is not necessary to start the +daemon on the monitoring system unless you wish to collect performance information +from it as well.</para> +<para>To stop <command>pmcd</command> immediately on a PCP collection system, +enter the following command:</para> +<literallayout class="monospaced"><userinput>${PCP_RC_DIR}/pmcd stop</userinput></literallayout> +</section> +<section id="LE58493-PARENT"> + +<title>Restarting an Unresponsive PMCD</title> +<para>Sometimes, if a daemon is not responding on a PCP collection system, the +problem can be resolved by stopping and then immediately restarting a fresh +instance of the daemon. If you need to stop and then immediately restart PMCD +on a PCP collection system, use the <literal>start</literal> argument provided +with the script in <filename>${PCP_RC_DIR}</filename>. The command syntax +is, as follows:</para> +<literallayout class="monospaced"><userinput>${PCP_RC_DIR}/pmcd start</userinput> </literallayout> +<para>On startup, <command>pmcd</command> looks for a configuration file at +<filename>${PCP_PMCDCONF_PATH}</filename>. This file specifies which agents +cover which performance metrics domains and how PMCD should make contact with +the agents. A comprehensive description of the configuration file syntax and +semantics can be found in the <command>pmcd(1)</command> man page. +</para> +<para>If the configuration is changed, <command>pmcd</command> reconfigures +itself when it receives the <literal>SIGHUP</literal> signal. Use the following +command to send the <literal>SIGHUP</literal> signal to the daemon:</para> +<literallayout class="monospaced"><userinput>${PCP_BINADM_DIR}/pmsignal -a -s HUP pmcd</userinput></literallayout> +<para>This is also useful when one of the PMDAs managed by <command>pmcd</command> +has failed or has been terminated by <command>pmcd</command>. Upon receipt +of the <literal>SIGHUP</literal> signal, <command>pmcd</command> restarts +any PMDA that is configured but inactive. The exception to this rule is the +case of a PMDA which must run with superuser privileges (where possible, this +is avoided) - for these PMDAs, a full <command>pmcd</command> restart must be +performed, using the process described earlier (not SIGHUP).</para> +</section> +<section id="id5190621"> + +<title>PMCD Diagnostics and Error Messages</title> +<para><indexterm id="ITch02-23"><primary>PMCD</primary><secondary>diagnostics +and error messages</secondary></indexterm>If there is a problem with <command> +pmcd</command>, the first place to investigate should be the <filename>pmcd.log</filename> file. +By default, this file is in the <filename>${PCP_LOG_DIR}/pmcd</filename> directory.</para> +</section> +<section id="id5190661"> + +<title>PMCD Options and Configuration Files</title> +<para><indexterm id="ITch02-26"><primary>PMCD</primary><secondary>configuration +files</secondary></indexterm>There are two files that control PMCD operation. +These are the <filename>${PCP_PMCDCONF_PATH}</filename> and <filename>${PCP_PMCDOPTIONS_PATH}</filename> files. +The <filename>pmcd.options</filename> +file contains the command line options used with PMCD; it is read +when the daemon is invoked by <literal>${PCP_RC_DIR}/pmcd</literal>. +The <filename>pmcd.conf</filename> file contains configuration information +regarding domain agents and the metrics that they monitor. +These configuration files are described in the following sections.</para> +<section id="id5190706"> + +<title>The <filename>pmcd.options</filename> File</title> +<para><indexterm id="ITch02-27"><primary>pmcd.options file</primary></indexterm>Command +line options for the PMCD are stored in the <filename>${PCP_PMCDOPTIONS_PATH}</filename> +file. The PMCD can be invoked directly from a shell prompt, or it can be invoked +by<literal> ${PCP_RC_DIR}/pmcd</literal> as part of the boot process. +It is usual and normal to invoke it using <literal>${PCP_RC_DIR}/pmcd</literal>, +reserving shell invocation for debugging purposes.</para> +<para>The PMCD accepts certain command line options to control its execution, +and these options are placed in the <filename>pmcd.options</filename> file +when <filename>${PCP_RC_DIR}/pmcd</filename> is being used to start the +daemon. The following options (amongst others) are available:</para> +<variablelist> +<varlistentry> +<term><literal>-i </literal> <replaceable>address</replaceable></term> +<listitem><para>For hosts with more than one network interface, this option +specifies the interface on which this instance of the PMCD accepts connections. +Multiple <literal>-i</literal> options may be specified. The default in the +absence of any <literal>-i</literal> option is for PMCD to accept connections +on all interfaces.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>-l </command> <replaceable>file</replaceable></term> +<listitem><para>Specifies a log file. If no <literal>-l</literal> option is +specified, the log file name is <filename>pmcd.log</filename> and it is created +in the directory <filename>${PCP_LOG_DIR}/pmcd/</filename>.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>-s </command> <replaceable>file</replaceable></term> +<listitem><para>Specifies the path to a local unix domain socket +(for platforms supporting this socket family only). +The default value is <filename>${PCP_RUN_DIR}/pmcd.socket</filename>.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>-t </command> <replaceable>seconds</replaceable></term> +<listitem><para><indexterm id="ITch02-28"><primary>PDU</primary></indexterm><indexterm id="IG3137188892"> +<primary>protocol data units</primary><see>PDU</see></indexterm>Specifies +the amount of time, in seconds, before PMCD times out on protocol data unit +(PDU) exchanges with PMDAs. If no time out is specified, the default is five +seconds. Setting time out to zero disables time outs (not recommended, PMDAs +should always respond quickly).</para> +<para>The time out may be dynamically modified by storing the number of seconds +into the metric <literal>pmcd.control.timeout</literal> using <command>pmstore</command>.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>-T </literal> <replaceable>mask</replaceable></term> +<listitem><para>Specifies whether connection and PDU tracing are turned on +for debugging purposes.</para> +</listitem></varlistentry> +</variablelist> +<para>See the <command>pmcd(1)</command> man page for complete +information on these options.</para> +<para>The default <filename>pmcd.options</filename> file shipped with PCP +is similar to the following:</para> +<literallayout class="monospaced"># command-line options to pmcd, uncomment/edit lines as required + +# longer timeout delay for slow agents +# -t 10 + +# suppress timeouts +# -t 0 + +# make log go someplace else +# -l /some/place/else + +# debugging knobs, see pmdbg(1) +# -D N +# -f + +# Restricting (further) incoming PDU size to prevent DOS attacks +# -L 16384 + +# enable event tracing bit fields +# 1 trace connections +# 2 trace PDUs +# 256 unbuffered tracing +# -T 3 + +# setting of environment variables for pmcd and +# the PCP rc scripts. See pmcd(1) and PMAPI(3). +# PMCD_WAIT_TIMEOUT=120</literallayout> +<para>The most commonly used options have been placed in this file for your +convenience. To uncomment and use an option, simply remove the pound sign +(#) at the beginning of the line with the option you wish to use. Restart +<command>pmcd</command> for the change to take effect; that is, as superuser, enter +the command:</para> +<literallayout class="monospaced"><userinput>${PCP_RC_DIR}/pmcd start</userinput></literallayout> +</section> +<section id="LE63226-PARENT"> + +<title>The <filename>pmcd.conf</filename> File</title> +<para><indexterm id="ITch02-29"><primary>pmcd.conf file</primary></indexterm>When +the PMCD is invoked, it reads its configuration file, which is <filename>${PCP_PMCDCONF_PATH}</filename>. +This file contains entries that specify the PMDAs used by this instance of +the PMCD and which metrics are covered by these PMDAs. Also, you may specify +access control rules in this file for the various hosts, users and groups on your network. +This file is described completely in the <command>pmcd(1)</command> man page.</para> +<para>With standard PCP operation (even if you have not created and added +your own PMDAs), you might need to edit this file in order to add any additional +access control you wish to impose. If you do not add access control rules, all access +for all operations is granted to the local host, and read-only access is granted to +remote hosts. The <filename>pmcd.conf</filename> file is automatically generated +during the software build process and on Linux, for example, is similar to the +following:</para> +<literallayout class="monospaced"> Performance Metrics Domain Specifications +# +# This file is automatically generated during the build +# Name Id IPC IPC Params File/Cmd +pmcd 2 dso pmcd_init ${PCP_PMDAS_DIR}/pmcd/pmda_pmcd.so +linux 60 dso linux_init ${PCP_PMDAS_DIR}/linux/pmda_linux.so +proc 3 pipe binary ${PCP_PMDAS_DIR}/proc/pmdaproc -d 3 +xfs 11 pipe binary ${PCP_PMDAS_DIR}/xfs/pmdaxfs -d 11 + +[access] +disallow * : store; +allow localhost : all;</literallayout> +<note><para>Even though PMCD does not run with <literal>root</literal> privileges, +you must be very careful not to configure PMDAs in this file if you are not +sure of their action. This is because all PMDAs are initially started as +<literal>root</literal> (allowing them to assume alternate identities, such as +<literal>postgres</literal> for example), after which <command>pmcd</command> +drops its privileges. +Pay close attention that permissions on this file are not +inadvertently downgraded to allow public write access.</para> +</note> +<para>Each entry in this configuration file contains rules that specify how +to connect the PMCD to a particular PMDA and which metrics the PMDA monitors. +A PMDA may be attached as a Dynamic Shared Object (DSO) or by using a socket +or a pair of pipes. The distinction between these attachment methods is described +below.</para> +<para>An entry in the <filename>pmcd.conf</filename> file looks like this: +</para> +<literallayout class="monospaced"><replaceable>label_name</replaceable> <replaceable>domain_number</replaceable> <replaceable>type</replaceable> <replaceable>path</replaceable></literallayout> +<para>The <replaceable>label_name</replaceable> field specifies a name for +the PMDA. The <replaceable>domain_number</replaceable> is an integer value +that specifies a domain of metrics for the PMDA. The <replaceable>type</replaceable> +field indicates the type of entry (DSO, socket, or pipe). The <replaceable> +path</replaceable> field is for additional information, and varies according +to the type of entry.</para> +<para>The following rules are common to DSO, socket, and pipe syntax:</para> +<variablelist> +<varlistentry> +<term><replaceable>label_name</replaceable></term> +<listitem><para>An alphanumeric string identifying the agent.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>domain_number</replaceable></term> +<listitem><para>An unsigned integer specifying the agent's domain.</para> +</listitem></varlistentry> +</variablelist> +<para>DSO entries follow this syntax:</para> +<synopsis><replaceable>label_name</replaceable> <replaceable>domain_number</replaceable> dso <replaceable>entry-point</replaceable> <replaceable>path</replaceable></synopsis> +<para>The following rules apply to the DSO syntax:</para> +<variablelist> +<varlistentry> +<term><literal>dso</literal></term> +<listitem><para>The entry type.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>entry-point</replaceable></term> +<listitem><para>The name of an initialization function called when the DSO +is loaded.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>path</replaceable></term> +<listitem><para>Designates the location of the DSO. An absolute path must be used. +On most platforms this will be a <literal>so</literal> suffixed file, on Windows it +is a <literal>dll</literal>, and on Mac OS X it is a <literal>dylib</literal> file.</para> +</listitem></varlistentry> +</variablelist> +<para>Socket entries in the <filename>pmcd.conf</filename> file follow this syntax:</para> +<synopsis><replaceable>label_name</replaceable> <replaceable>domain_number</replaceable> socket <replaceable>addr_family</replaceable> <replaceable>address</replaceable> <replaceable>command</replaceable> <optional><replaceable>args</replaceable></optional> </synopsis> +<para>The following rules apply to the socket syntax:</para> +<variablelist> +<varlistentry> +<term><literal>socket</literal></term> +<listitem><para>The entry type.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>addr_family</replaceable></term> +<listitem><para>Specifies if the socket is <literal>AF_INET</literal>, <literal>AF_IPV6</literal> +or <literal>AF_UNIX</literal>. If the socket is <literal>INET</literal>, the word <literal>inet</literal> +appears in this place. If the socket is <literal>IPV6</literal>, the word <literal>ipv6</literal> +appears in this place. If the socket is <literal>UNIX</literal>, +the word <literal>unix</literal> appears in this place.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>address</replaceable></term> +<listitem><para>Specifies the address of the socket. For INET or IPv6 sockets, this +is a port number or port name. For UNIX sockets, this is the name of the PMDA's +socket on the local host.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>command</replaceable></term> +<listitem><para>Specifies a command to start the PMDA when the PMCD is invoked +and reads the configuration file.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>args</replaceable></term> +<listitem><para>Optional arguments for <replaceable>command</replaceable>. +</para> +</listitem></varlistentry> +</variablelist> +<para>Pipe entries in the <filename>pmcd.conf</filename> file follow this syntax:</para> +<synopsis><replaceable>label_name</replaceable> <replaceable>domain_number</replaceable> pipe <replaceable>protocol</replaceable> <replaceable>command</replaceable> <optional><replaceable>args</replaceable></optional></synopsis> +<para>The following rules apply to the pipe syntax:</para> +<variablelist> +<varlistentry> +<term><literal>pipe</literal></term> +<listitem><para>The entry type.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>protocol</replaceable></term> +<listitem><para>Specifies whether a text-based or a binary PCP protocol should +be used over the pipes. Historically, this parameter was able to be “text” +or “binary.” The text-based protocol has long since been deprecated and +removed, however, so nowadays “binary” is the only valid value here. +</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>command</replaceable></term> +<listitem><para>Specifies a command to start the PMDA when the PMCD is invoked +and reads the configuration file.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>args</replaceable></term> +<listitem><para>Optional arguments for <replaceable>command</replaceable>. +</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5191707"> + +<title>Controlling Access to PMCD with <filename>pmcd.conf</filename></title> +<para><indexterm id="ITch02-30"><primary>pmcd.conf file</primary></indexterm>You +can place this option extension in the <filename>pmcd.conf</filename> file +to control access to performance metric data based on hosts, users and groups. +To add an access control section, begin by placing the following line at the end +of your <filename>pmcd.conf</filename> file:</para> +<literallayout class="monospaced">[access] </literallayout> +<para>Below this line, you can add entries of the following forms:</para> +<literallayout class="monospaced">allow hosts <replaceable>hostlist</replaceable> : <replaceable>operations</replaceable> ; disallow hosts <replaceable>hostlist</replaceable> : <replaceable>operations</replaceable> ; +allow users <replaceable>userlist</replaceable> : <replaceable>operations</replaceable> ; disallow users <replaceable>userlist</replaceable> : <replaceable>operations</replaceable> ; +allow groups <replaceable>grouplist</replaceable> : <replaceable>operations</replaceable> ; disallow groups <replaceable>grouplist</replaceable> : <replaceable>operations</replaceable> ; +</literallayout> +<para>The keywords <replaceable>users</replaceable>, <replaceable>groups</replaceable> +and <replaceable>hosts</replaceable> can be used in either plural or singular form.</para> +<para>The <replaceable>userlist</replaceable> and <replaceable>grouplist</replaceable> +fields are comma-separated lists of authenticated users and groups from the +local <filename>/etc/passwd</filename> and <filename>/etc/groups</filename> files, +NIS (network information service) or LDAP (lightweight directory access protocol) service.</para> +<para>The <replaceable>hostlist</replaceable> is a comma-separated list of +host identifiers; the following rules apply:</para> +<itemizedlist> +<listitem><para>Host names must be in the local system's <filename>/etc/hosts</filename> +file or known to the local DNS (domain name service).</para> +</listitem> +<listitem><para>IP and IPv6 addresses may be given in the usual numeric notations.</para> +</listitem> +<listitem><para>A wildcarded IP or IPv6 address may be used to specify groups of hosts, +with the single wildcard character * as the last-given component of the address. +The wildcard .* refers to all IP (IPv4) addresses. +The wildcard :* refers to all IPv6 addresses. +If an IPv6 wildcard contains a :: component, then the final * refers to the final 16 bits of +the address only, otherwise it refers to the remaining unspecified bits of the address.</para> +</listitem> +</itemizedlist> +<para>The wildcard ``*'' refers to all users, groups or host addresses. +Names of users, groups or hosts may not be wildcarded.</para> +<para>For example, the following <replaceable>hostlist</replaceable> entries +are all valid:</para> +<literallayout class="monospaced">babylon +babylon.acme.com +123.101.27.44 +localhost +155.116.24.* +192.* +.* +fe80::223:14ff:feaf:b62c +fe80::223:14ff:feaf:* +fe80:* +:* +*</literallayout> +<para>The <replaceable>operations</replaceable> field can be any of the following: +</para> +<itemizedlist> +<listitem><para>A comma-separated list of the operation types described below. +</para> +</listitem> +<listitem><para>The word <firstterm>all</firstterm> to allow or disallow all +operations as specified in the first field.</para> +</listitem> +<listitem><para>The words <firstterm>all except</firstterm> and a list of +operations. This entry allows or disallows all operations as specified in +the first field except those listed.</para> +</listitem> +<listitem><para>The phrase <firstterm>maximum</firstterm> N <firstterm>connections</firstterm> +to set an upper bound (N) on the number of connections an individual host, user or +group of users may make. This can only be added to the <replaceable>operations</replaceable> +list of an allow statement.</para> +</listitem> +</itemizedlist> +<para>The operations that can be allowed or disallowed are as follows:</para> +<variablelist condition="sgi_termlength:narrow"> +<varlistentry> +<term><literal>fetch</literal></term> +<listitem><para>Allows retrieval of information from the PMCD. This may be +information about a metric (such as a description, instance domain, or help +text) or an actual value for a metric.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>store</literal></term> +<listitem><para>Allows the PMCD to store metric values in PMDAs that permit +store operations. Be cautious in allowing this operation, because it may be +a security opening in large networks, although the PMDAs shipped with the +PCP package typically reject store operations, except for selected performance +metrics where the effect is benign.</para> +</listitem></varlistentry> +</variablelist> +<para>For example, here is a sample access control portion of a +<filename>${PCP_PMCDCONF_PATH}</filename> file:</para> +<literallayout class="monospaced">allow hosts babylon, moomba : all ; +disallow user sam : all ; +allow group dev : fetch ; +allow hosts 192.127.4.* : fetch ; +disallow host gate-inet : store ; </literallayout> +<para>Complete information on access control syntax rules in the +<filename>pmcd.conf</filename> file can be found in the <command>pmcd(1)</command> +man page.</para> +</section> +</section> +</section> +<section id="LE43202-PARENT"> + +<title>Managing Optional PMDAs</title> +<para><indexterm id="ITch02-31"><primary>PMDA</primary><secondary>managing +optional agents</secondary></indexterm>Some Performance Metrics Domain Agents +(PMDAs) shipped with Performance Co-Pilot (PCP) are designed to be installed +and activated on every collector host, for example, <literal>linux</literal>, +<literal>windows</literal>, <literal>darwin</literal>, <literal>pmcd</literal>, +and <literal>process</literal> PMDAs.</para> +<para>Other PMDAs are designed for optional activation and require some user +action to make them operational. In some cases these PMDAs expect local site +customization to reflect the operational environment, the system configuration, +or the production workload. This customization is typically supported by interactive +installation scripts for each PMDA.</para> +<para>Each PMDA has its own directory located below <filename>${PCP_PMDAS_DIR}</filename>. +Each directory contains a <filename>Remove</filename> script to unconfigure +the PMDA, remove the associated metrics from the PMNS, and restart the <command> +pmcd</command> daemon; and an <filename>Install</filename> script to install +the PMDA, update the PMNS, and restart the PMCD daemon.</para> +<para>As a shortcut mechanism to support automated PMDA installation, a file named +<filename>.NeedInstall</filename> can be created in a PMDA directory below +<filename>${PCP_PMDAS_DIR}</filename>. The next restart of PCP services will +invoke that PMDAs installation automatically, with default options taken. +</para> +<section id="LE31599-PARENT"> + +<title>PMDA Installation on a PCP Collector Host</title> +<para><indexterm id="ITch02-32"><primary>PMDA</primary><secondary>installation +</secondary></indexterm>To install a PMDA you must perform a collector installation +for each host on which the PMDA is required to export performance metrics. +PCP provides a distributed metric namespace (PMNS) and metadata, so it is not necessary +to install PMDAs (with their associated PMNS) on PCP monitor hosts.</para> +<para><indexterm id="ITch02-33"><primary>collector hosts</primary></indexterm> +You need to update the PMNS, configure the PMDA, and notify PMCD. +The <literal>Install</literal> script for each PMDA automates these operations, as follows: +</para> +<orderedlist><listitem><para>Log in as <literal>root</literal> (the superuser). +</para> +</listitem><listitem><para>Change to the PMDA's directory as shown in the following +example:</para> +<literallayout class="monospaced"><userinput>cd ${PCP_PMDAS_DIR}/cisco</userinput></literallayout> +</listitem><listitem><para><indexterm id="IG3137188893"><primary>PMD</primary></indexterm><indexterm id="IG3137188894"> +<primary>Performance Metrics Domain</primary><see>PMD</see></indexterm>In +the unlikely event that you wish to use a non-default Performance Metrics +Domain (PMD) assignment, determine the current PMD assignment:</para> +<literallayout class="monospaced"><userinput>cat domain.h</userinput></literallayout> +<para><indexterm id="IG3137188895"><primary>${PCP_VAR_DIR}/pmns/stdpmid file</primary></indexterm><indexterm id="IG3137188896"> +<primary>${PCP_PMCDCONF_PATH} file</primary></indexterm>Check that +there is no conflict in the PMDs as defined in <filename>${PCP_VAR_DIR}/pmns/stdpmid</filename> +and the other PMDAs currently in use (listed in <filename>${PCP_PMCDCONF_PATH}</filename>). +Edit <filename>domain.h</filename> to assign the new domain number if there +is a conflict (this is highly unlikely to occur in a regular PCP installation).</para> +</listitem><listitem><para>Enter the following command:</para> +<literallayout class="monospaced"><userinput>./Install</userinput></literallayout> +<para>You may be prompted to enter some local parameters or configuration +options. The script applies all required changes to the control files and +to the PMNS, and then notifies PMCD. <xref linkend="Z929138022sdc"/> is illustrative +of the interactions:</para> +<example id="Z929138022sdc"> +<title>PMNS Installation Output +</title> +<literallayout class="monospaced">You will need to choose an appropriate configuration for +installation of the “cisco” Performance Metrics Domain Agent (PMDA). + + collector collect performance statistics on this system + monitor allow this system to monitor local and/or remote systems + both collector and monitor configuration for this system + +Please enter c(ollector) or m(onitor) or b(oth) [b] <userinput>collector</userinput> + +Cisco hostname or IP address? [return to quit] <userinput>wanmelb</userinput> + +A user-level password may be required for Cisco “show int” command. + If you are unsure, try the command + $ telnet wanmelb + and if the prompt “Password:” appears, a user-level password is + required; otherwise answer the next question with an empty line. + +User-level Cisco password? <userinput>********</userinput> +Probing Cisco for list of interfaces ... + +Enter interfaces to monitor, one per line in the format +tX where “t” is a type and one of “e” (Ethernet), or “f” (Fddi), or +“s” (Serial), or “a” (ATM), and “X” is an interface identifier +which is either an integer (e.g. 4000 Series routers) or two +integers separated by a slash (e.g. 7000 Series routers). + +The currently unselected interfaces for the Cisco “wanmelb” are: + e0 s0 s1 +Enter “quit” to terminate the interface selection process. +Interface? [e0] <userinput>s0</userinput> + +The currently unselected interfaces for the Cisco “wanmelb” are: + e0 s1 +Enter “quit” to terminate the interface selection process. +Interface? [e0] <userinput>s1</userinput> + +The currently unselected interfaces for the Cisco “wanmelb” are: + e0 +Enter “quit” to terminate the interface selection process. +Interface? [e0] <userinput>quit</userinput> + +Cisco hostname or IP address? [return to quit] +Updating the Performance Metrics Name Space (PMNS) ... +Installing pmchart view(s) ... +Terminate PMDA if already installed ... +Installing files ... +Updating the PMCD control file, and notifying PMCD ... +Check cisco metrics have appeared ... 5 metrics and 10 values</literallayout> +</example> +</listitem></orderedlist> +</section> +<section id="id5192380"> + +<title>PMDA Removal on a PCP Collector Host</title> +<para><indexterm id="ITch02-35"><primary>PMDA</primary><secondary>removal +</secondary></indexterm>To remove a PMDA, you must perform a collector removal +for each host on which the PMDA is currently installed.</para> +<para>The PMNS needs to be updated, the PMDA unconfigured, and PMCD notified. +The <literal>Remove</literal> script for each PMDA automates these operations, +as follows:</para> +<orderedlist><listitem><para>Log in as <literal>root</literal> (the superuser). +</para> +</listitem><listitem><para>Change to the PMDA's directory as shown in the following +example:</para> +<literallayout class="monospaced"><userinput>cd ${PCP_PMDAS_DIR}/elasticsearch</userinput></literallayout> +</listitem><listitem><para>Enter the following command:</para> +<literallayout class="monospaced"><userinput>./Remove</userinput></literallayout> +<para>The following output illustrates the result:</para> +<literallayout class="monospaced">Culling the Performance Metrics Name Space ... +elasticsearch ... done +Updating the PMCD control file, and notifying PMCD ... +Removing files ... +Check elasticsearch metrics have gone away ... OK</literallayout> +</listitem></orderedlist> +</section> +</section> +<section id="LE70712-PARENT"> + +<title>Troubleshooting</title> +<para><indexterm id="ITch02-38"><primary>troubleshooting</primary><secondary> +PMCD</secondary></indexterm>The following sections offer troubleshooting advice +on the Performance Metrics Name Space (PMNS), missing and incomplete values +for performance metrics, kernel metrics and the PMCD.</para> +<para>Advice for troubleshooting the archive logging system is provided in <xref linkend="LE93354-PARENT"/>.</para> +<section id="LE97133-PARENT"> + +<title>Performance Metrics Name Space</title> +<para><indexterm id="IG3137188897"><primary>pminfo tool</primary><secondary>displaying the PMNS +</secondary></indexterm><indexterm id="IG3137188898"><primary>PMNS</primary><secondary>troubleshooting +</secondary></indexterm>To display the active PMNS, use the <literal>pminfo</literal> +command; see the <command>pminfo(1)</command> man page.</para> +<para>The PMNS at the collector host is updated whenever a PMDA is installed +or removed, and may also be updated when new versions of PCP are +installed. During these operations, the PMNS is typically updated by merging the +(plaintext) namespace components from each installed PMDA. +These separate PMNS components reside in the <filename>${PCP_VAR_DIR}/pmns</filename> +directory and are merged into the <filename>root</filename> file there.</para> +</section> +<section id="LE90170-PARENT"> + +<title>Missing and Incomplete Values for Performance Metrics +</title> +<para><indexterm id="ITch02-39"><primary>performance metrics</primary><secondary> +missing and incomplete values</secondary></indexterm>Missing or incomplete +performance metric values are the result of their unavailability.</para> +<section id="LE89271-PARENT"> + +<title>Metric Values Not Available</title> +<para>The following symptom has a known cause and resolution:</para> +<variablelist> +<varlistentry> +<term>Symptom:</term> +<listitem><para>Values for some or all of the instances of a performance metric +are not available.</para> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para>This can occur as a consequence of changes in the installation +of modules (for example, a DBMS or an application package) that provide the +performance instrumentation underpinning the PMDAs. Changes in the selection +of modules that are installed or operational, along with changes in the version +of these modules, may make metrics appear and disappear over time.</para> +<para>In simple terms, the PMNS contains a metric name, but when that metric +is requested, no PMDA at the collector host supports the metric.</para> +<para>For archive logs, the collection of metrics to be logged is a subset +of the metrics available, so utilities replaying from a PCP archive log may +not have access to all of the metrics available from a live (PMCD) source. +</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para>Make sure the underlying instrumentation is available and +the module is active. Ensure that the PMDA is running on the host to be monitored. +If necessary, create a new archive log with a wider range of metrics to be +logged.</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +<section id="LE76751-PARENT"> + +<title>Kernel Metrics and the PMCD</title> +<para><indexterm id="IG3137188899"><primary>troubleshooting</primary><secondary>Kernel metrics +</secondary></indexterm><indexterm id="IG31371888100"><primary>troubleshooting</primary><secondary> +PMCD</secondary></indexterm>The following issues involve the kernel metrics and the PMCD:</para> +<itemizedlist> +<listitem><para>Cannot connect to remote PMCD</para> +</listitem> +<listitem><para>PMCD not reconfiguring after hang-up</para> +</listitem> +<listitem><para>PMCD does not start</para> +</listitem></itemizedlist> +<section id="id5192807"> + +<title>Cannot Connect to Remote PMCD</title> +<para><indexterm id="IG31371888101"><primary>PMCD</primary><secondary>remote connection</secondary> +</indexterm><indexterm id="ITch02-42"><primary>troubleshooting</primary><secondary> +general utilities</secondary></indexterm>The following symptom has a known +cause and resolution:</para> +<variablelist> +<varlistentry> +<term>Symptom:</term> +<listitem><para><indexterm id="IG31371888102"><primary>pmchart tool</primary><secondary>remote +PMCD</secondary></indexterm><indexterm id="IG31371888103"><primary>pmie tool</primary><secondary> +remote PMCD</secondary></indexterm><indexterm id="IG31371888104"><primary>pmlogger tool</primary> +<secondary>remote PMCD</secondary></indexterm>A PCP client tool (such as <literal>pmchart</literal>, <literal>pmie</literal>, or <literal>pmlogger</literal>) +complains that it is unable to connect to a remote PMCD (or establish a PMAPI +context), but you are sure that PMCD is active on the remote host.</para> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para><indexterm id="IG31371888105"><primary>TCP/IP</primary><secondary>remote PMCD +</secondary></indexterm>To avoid hanging applications for the duration of TCP/IP time +outs, the PMAPI library implements its own time out when trying to establish +a connection to a PMCD. If the connection to the host is over a slow network, +then successful establishment of the connection may not be possible before +the time out, and the attempt is abandoned.</para> +<para>Alternatively, there may be a firewall in-between the client tool and PMCD which is blocking the connection attempt.</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para>Establish that the PMCD on <replaceable>far-away-host</replaceable> +is really alive, by connecting to its control port (TCP port number 44321 by +default):<literallayout class="monospaced"><userinput>telnet far-away-host 44321</userinput></literallayout></para> +<para>This response indicates the PMCD is not running and needs restarting: +</para> +<literallayout class="monospaced">Unable to connect to remote host: Connection refused</literallayout> +<para>To restart the PMCD on that host, enter the following command:<literallayout class="monospaced"><userinput>${PCP_RC_DIR}/pmcd start</userinput></literallayout></para> +<para>This response indicates the PMCD is running:<literallayout class="monospaced">Connected to far-away-host </literallayout></para> +<para><indexterm id="IG31371888106"><primary>PMCD_CONNECT_TIMEOUT variable</primary></indexterm>Interrupt +the <literal>telnet</literal> session, increase the PMAPI time out by setting +the <literal>PMCD_CONNECT_TIMEOUT</literal> environment variable to some number +of seconds (60 for instance), and try the PCP client tool again.</para> +<para>If these techniques are ineffective, it is likely an intermediary firewall is blocking the client from accessing the PMCD port - resolving such issues is firewall-host platform-specific and cannot practically be covered here.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5193049"> + +<title>PMCD Not Reconfiguring after <literal>SIGHUP</literal></title> +<para><indexterm id="IG31371888107"><primary>SIGHUP signal</primary></indexterm>The following +symptom has a known cause and resolution:</para> +<variablelist> +<varlistentry> +<term>Symptom</term> +<listitem><para>PMCD does not reconfigure itself after receiving the <literal>SIGHUP</literal> signal.</para> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para><indexterm id="IG31371888108"><primary>pmcd.conf file</primary> +</indexterm>If there is a syntax error in <filename>${PCP_PMCDCONF_PATH}</filename>, +PMCD does not use the contents of the file. This can lead to +situations in which the configuration file and PMCD's internal state do not +agree.</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para>Always monitor PMCD's log. For example, use the following +command in another window when reconfiguring PMCD, to watch errors occur:<literallayout class="monospaced"><userinput>tail -f ${PCP_LOG_DIR}/pmcd/pmcd.log</userinput></literallayout></para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5193138"> + +<title>PMCD Does Not Start</title> +<para><indexterm id="IG31371888109"><primary>PMCD</primary><secondary>not starting</secondary> +</indexterm>The following symptom has a known cause and resolution:</para> +<variablelist> +<varlistentry> +<term>Symptom:</term> +<listitem><indexterm id="IG31371888110"><primary>${PCP_LOGDIR}/pmcd/pmcd.log file</primary></indexterm> +<para>If the following messages appear in the PMCD log +(<filename>${PCP_LOG_DIR}/pmcd/pmcd.log</filename>), consider the cause +and resolution:</para> +<literallayout class="monospaced">pcp[27020] Error: OpenRequestSocket(44321) bind: Address already in +use +pcp[27020] Error: pmcd is already running +pcp[27020] Error: pmcd not started due to errors!</literallayout> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para>PMCD is already running or was terminated before it could +clean up properly. The error occurs because the socket it advertises for client +connections is already being used or has not been cleared by the kernel.</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para>Start PMCD as <literal>root</literal> (superuser) by typing:<literallayout class="monospaced"><userinput>${PCP_RC_DIR}/pmcd start</userinput></literallayout></para> +<para>Any existing PMCD is shut down, and a new one is started in such a way +that the symptomatic message should not appear.</para> +<para>If you are starting PMCD this way and the symptomatic message appears, +a problem has occurred with the connection to one of the deceased PMCD's clients. +</para> +<para>This could happen when the network connection to a remote client is +lost and PMCD is subsequently terminated. The system may attempt to keep the +socket open for a time to allow the remote client a chance to reestablish +the connection and read any outstanding data.</para> +<para><indexterm id="IG31371888111"><primary>netstat command</primary></indexterm>The only solution +in these circumstances is to wait until the socket times out and the kernel +deletes it. This <command>netstat</command> command displays the status of +the socket and any connections:<literallayout class="monospaced"><userinput>netstat -ant | grep 44321</userinput></literallayout></para> +<para>If the socket is in the <literal>FIN_WAIT</literal> or <literal>TIME_WAIT</literal> state, then you must wait for it to be deleted. Once the command +above produces no output, PMCD may be restarted. Less commonly, you may have +another program running on your system that uses the same Internet port number +(44321) that PMCD uses.</para> +<para><indexterm id="IG31371888112"><primary>PCPIntro command</primary></indexterm><indexterm id="IG31371888113"> +<primary>PMCD_PORT variable</primary></indexterm>Refer to the <command>PCPIntro(1)</command> +man page for a description of how to override the default +PMCD port assignment using the <literal>PMCD_PORT</literal> environment variable. +</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +</section> +</chapter> + + + +<chapter id="LE94335-PARENT"> + +<title>Common Conventions and Arguments</title> +<para><indexterm id="ITch03-0"><primary>PCP</primary><secondary>conventions +</secondary></indexterm> <indexterm id="ITch03-1"><primary>conventions +</primary></indexterm><indexterm id="Z1033415461tls"><primary>user interface +components</primary></indexterm> This chapter deals with the user interface +components that are common to most text-based utilities that make up the +monitor portion of Performance Co-Pilot (PCP). These are the major sections +in this chapter:</para> +<itemizedlist> +<listitem><para><xref linkend="LE85600-PARENT"/>, details some basic standards +used in the development of PCP tools.</para> +</listitem> +<listitem><para><xref linkend="LE68596-PARENT"/>, details other options +to use with PCP tools.</para> +</listitem> +<listitem><para><xref linkend="LE76997-PARENT"/>, describes the time control +dialog and time-related command line options available for use with PCP +tools.</para> +</listitem> +<listitem><para><xref linkend="LE61303-PARENT"/>, describes the environment +variables supported by PCP tools.</para> +</listitem> +<listitem><para><xref linkend="LE12082-PARENT"/>, describes how to execute +PCP tools that must retrieve performance data from the Performance Metrics +Collection Daemon (PMCD) on the other side of a TCP/IP security firewall. +</para> +</listitem> +<listitem><para><xref linkend="LE17322-PARENT"/>, covers some uncommon +scenarios that may compromise performance metric integrity over the short +term.</para> +</listitem></itemizedlist> +<para><indexterm id="ITch03-2"><primary>PCP</primary><secondary>naming +conventions</secondary></indexterm>Many of the utilities provided with +PCP conform to a common set of naming and syntactic conventions for command +line arguments and options. This section outlines these conventions and +their meaning. The options may be generally assumed to be honored for +all utilities supporting the corresponding functionality.</para> +<para>In all cases, the man pages for each utility fully describe the +supported command arguments and options.</para> +<para><indexterm id="IG31371888114"><primary>pmrun tool</primary></indexterm>Command line +options are also relevant when starting PCP applications from the desktop +using the <keycap>Alt</keycap> double-click method. This technique launches +the <command>pmrun</command> program to collect additional arguments to +pass along when starting a PCP application.</para> +<section id="LE85600-PARENT"> + +<title>Alternate Metrics Source Options</title> +<para>The default source of performance metrics is from PMCD on the local +host. This default <command>pmcd</command> connection will be made using +the Unix domain socket, if the platform supports that, else a localhost +Inet socket connection is made. +This section describes how to obtain metrics from sources other +than this default.</para> +<section id="id5193612"> + +<title>Fetching Metrics from Another Host</title> +<para><indexterm id="ITch03-3"><primary>fetching metrics</primary></indexterm><indexterm id="IG31371888115"> +<primary>pmchart tool</primary><secondary>fetching metrics</secondary> +</indexterm><indexterm id="IG31371888116"><primary>pmie tool</primary><secondary>fetching +metrics</secondary></indexterm>The option <literal>-h</literal> <replaceable>host</replaceable> +directs any PCP utility (such as <literal>pmchart</literal> +or <literal>pmie</literal>) to make a connection with the PMCD instance +running on <replaceable>host</replaceable>. Once established, this connection +serves as the principal real-time source of performance metrics and metadata. +The <replaceable>host</replaceable> specification may be more than a simple host +name or address - it can also contain decorations specifying protocol type (secure +or not), authentication information, and other connection attributes. +Refer to the <command>PCPIntro(1)</command> man page for full details of these, +and examples of use of these specifications can also be found in the +<citetitle>PCP Tutorials and Case Studies</citetitle> companion document.</para> +</section> +<section id="id5193712"> + +<title>Fetching Metrics from an Archive Log</title> +<para><indexterm id="ITch03-6"><primary>fetching metrics</primary></indexterm><indexterm id="ITch03-5"><primary>archive logs</primary><secondary>fetching metrics +</secondary></indexterm><indexterm id="ITch03-8"><primary>PCP</primary> +<secondary>log file option</secondary></indexterm>The option <literal>-a</literal> +<replaceable>archive</replaceable> directs the utility to +treat the PCP archive logs with base name <replaceable>archive</replaceable> +as the principal source of performance metrics and metadata.</para> +<para><indexterm id="IG31371888117"><primary>pmlogger tool</primary><secondary>archive logs +</secondary></indexterm>PCP archive logs are created with <command>pmlogger</command>. +Most PCP utilities operate with equal facility for performance +information coming from either a real-time feed via PMCD on some host, +or for historical data from a PCP archive log. For more information on +archive logs and their use, see <xref linkend="LE93354-PARENT"/>.</para> +<para><indexterm id="ITch03-9"><primary>archive logs</primary><secondary> +physical filenames</secondary></indexterm>The base name (<filename>archive</filename>) +of the PCP archive log used with the <literal>-a</literal> +option implies the existence of the files created automatically by <command>pmlogger</command>, +as listed in <xref linkend="id5193871"/>.</para> +<table id="id5193871" frame="topbot"> + +<title>Physical Filenames for Components of a PCP Archive Log</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="100*"/> +<colspec colwidth="296*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Filename</para></entry> +<entry align="left" valign="bottom"><para>Contents</para></entry></row> +</thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><filename>archive.</filename><replaceable> +index</replaceable><emphasis role="bold"/></para></entry> +<entry align="left" valign="top"><para>Temporal index for rapid access +to archive contents</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><filename>archive.</filename><replaceable> +meta</replaceable></para></entry> +<entry align="left" valign="top"><para>Metadata descriptions for performance +metrics and instance domains appearing in the archive</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><filename>archive.N</filename></para></entry> +<entry align="left" valign="top"><para>Volumes of performance metrics +values, for <filename>N</filename> = 0,1,2,...</para></entry></row></tbody> +</tgroup></table> +<para>Some tools are able to concurrently process multiple PCP archive +logs (for example, for retrospective analysis of performance across multiple +hosts), and accept either multiple <command>-a</command> options or a +comma separated list of archive names following the <command>-a</command> +option.</para> +<note><para>The <command>-h</command> and <command>-a</command> options +are almost always mutually exclusive. Currently, <command>pmchart</command> +is the exception to this rule but other tools may continue to blur this +line in the future.</para> +</note> +</section> +</section> +<section id="LE68596-PARENT"> + +<title>General PCP Tool Options</title> +<para><indexterm id="IG31371888118"><primary>tool options</primary></indexterm>The following +sections provide information relevant to most of the PCP tools. It is +presented here in a single place for convenience.</para> +<section id="id5194103"> + +<title>Common Directories and File Locations</title> +<para><indexterm id="IG31371888119"><primary>common directories</primary></indexterm><indexterm id="IG31371888120"> +<primary>file locations</primary></indexterm>The following files and directories +are used by the PCP tools as repositories for option and configuration +files and for binaries:</para> +<variablelist condition="sgi_termlength:wide"> +<varlistentry> +<term><filename>${PCP_DIR}/etc/pcp.env</filename></term> +<listitem><para><indexterm id="IG31371888121"><primary>${PCP_DIR}/etc/pcp.env file</primary></indexterm>Script +to set PCP run-time environment variables.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_DIR}/etc/pcp.conf</filename></term> +<listitem><para><indexterm id="IG31371888122"><primary>${PCP_DIR}/etc/pcp.conf file</primary></indexterm>PCP +configuration and environment file.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_PMCDCONF_PATH}</filename></term> +<listitem><para><indexterm id="IG31371888123"><primary>${PCP_PMCDCONF_PATH} file</primary></indexterm> +<indexterm id="IG31371888124"><primary>PMCD</primary><secondary>${PCP_PMCDCONF_PATH} file +</secondary></indexterm>Configuration file for Performance Metrics +Collection Daemon (PMCD). Sets environment variables, including <literal>PATH</literal>.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_BINADM_DIR}/pmcd</filename></term> +<listitem><para><indexterm id="IG31371888125"><primary>${PCP_BINADM_DIR}/pmcd file</primary> +</indexterm>The PMCD binary.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_PMCDOPTIONS_PATH}</filename></term> +<listitem><para><indexterm id="IG31371888126"><primary>${PCP_PMCDOPTIONS_PATH} file +</primary></indexterm>Command line options for PMCD.<?sgi-newline?> +</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_RC_DIR}/pmcd</filename></term> +<listitem><para><indexterm id="IG31371888127"><primary>${PCP_RC_DIR}/pmcd file</primary> +</indexterm>The PMCD startup script.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_BIN_DIR}/<replaceable>pcptool</replaceable></filename></term> +<listitem><para>Directory containing PCP tools such as <command>pmstat +</command>, <command>pminfo</command>, <command>pmlogger</command>, <command>pmlogsummary</command>, +<command>pmchart</command>, <command>pmie</command>, and so on.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_SHARE_DIR}</filename></term> +<listitem><para>Directory containing shareable PCP-specific files and +repository directories such as <command>bin</command>, <command>demos</command>, +<command>examples</command> and <command>lib</command>. </para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_VAR_DIR}</filename></term> +<listitem><para>Directory containing non-shareable (that is, per-host) +PCP specific files and repository directories.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_BINADM_DIR}/<replaceable>pcptool</replaceable></filename></term> +<listitem><para>PCP tools that are typically not executed directly by +the end user such as <command>pmcd_wait</command>.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_SHARE_DIR}/lib/<replaceable>pcplib</replaceable></filename></term> +<listitem><para>Miscellaneous PCP libraries and executables.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_PMDAS_DIR}</filename></term> +<listitem><para> Performance Metric Domain Agents (PMDAs), one directory +per PMDA.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_VAR_DIR}/config</filename></term> +<listitem><para>Configuration files for PCP tools, typically with one +directory per tool.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_DEMOS_DIR}</filename></term> +<listitem><para>Demonstration data files and example programs.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_LOG_DIR}</filename></term> +<listitem><para>By default, diagnostic and trace log files generated by +PMCD and PMDAs. Also, the PCP archive logs are managed in one directory +per logged host below here.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_VAR_DIR}/pmns</filename></term> +<listitem><para>Files and scripts for the Performance Metrics Name Space +(PMNS).</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5194616"> + +<title>Alternate Performance Metric Name Spaces</title> +<para><indexterm id="ITch03-10"><primary>PMNS</primary><secondary>PMNS +</secondary></indexterm>The Performance Metrics Name Space (PMNS) defines +a mapping from a collection of human-readable names for performance metrics +(convenient to the user) into corresponding internal identifiers (convenient +for the underlying implementation).</para> +<para>The distributed PMNS used in PCP avoids most requirements for an +alternate PMNS, because clients' PMNS operations are supported at the +Performance Metrics Collection Daemon (PMCD) or by means of PMNS data +in a PCP archive log. The distributed PMNS is the default, but alternates +may be specified using the <command>-n</command> <replaceable>namespace</replaceable> +argument to the PCP tools. When a PMNS is maintained on a host, it is likely +to reside in the <filename>${PCP_VAR_DIR}/pmns</filename> directory.</para> +</section> +</section> +<section id="LE76997-PARENT"> + +<title>Time Duration and Control</title> +<para><indexterm id="IG31371888129"><primary>time duration</primary></indexterm>The periodic +nature of sampling performance metrics and refreshing the displays of +the PCP tools makes specification and control of the temporal domain a +common operation. In the following sections, the services and conventions +for specifying time positions and intervals are described.</para> +<section id="LE96583-PARENT"> + +<title>Performance Monitor Reporting Frequency and +Duration</title> +<para><indexterm id="IG31371888130"><primary>reporting frequency</primary></indexterm><indexterm id="IG31371888131"> +<primary>duration</primary></indexterm>Many of the performance monitoring +utilities have periodic reporting patterns. The <literal>-t </literal> <replaceable>interval</replaceable> +and <literal>-s</literal> <replaceable>samples</replaceable> options +are used to control the sampling (reporting) interval, +usually expressed as a real number of seconds (<replaceable>interval</replaceable>), +and the number of <replaceable>samples</replaceable> to be reported, respectively. +In the absence of the <literal>-s</literal> flag, the default behavior +is for the performance monitoring utilities to run until they are explicitly +stopped.</para> +<para><indexterm id="IG31371888132"><primary>PCPIntro command</primary></indexterm>The <replaceable> +interval</replaceable> argument may also be expressed in terms of minutes, +hours, or days, as described in the <command>PCPIntro(1)</command> +man page.</para> +</section> +<section id="LE14729-PARENT"> + +<title>Time Window Options</title> +<para><indexterm id="IG31371888133"><primary>time window options</primary></indexterm><indexterm id="IG31371888134"> +<primary>window options</primary></indexterm>The following options may +be used with most PCP tools (typically when the source of the performance +metrics is a PCP archive log) to tailor the beginning and end points of +a display, the sample origin, and the sample time alignment to your convenience. +</para> +<para>The <literal>-S</literal>, <literal>-T</literal>, <literal>-O</literal> +and <literal>-A</literal> command line options are used by PCP applications +to define a time window of interest.</para> +<variablelist condition="sgi_termlength:standard"> +<varlistentry> +<term><literal>-S </literal> <replaceable>duration</replaceable></term> +<listitem><para>The start option may be used to request that the display +start at the nominated time. By default, the first sample of performance +data is retrieved immediately in real-time mode, or coincides with the +first sample of data in a PCP archive log in archive mode. For archive +mode, the <literal>-S</literal> option may be used to specify a later +time for the start of sampling. By default, if <replaceable>duration</replaceable> +is an integer, the units are assumed to be seconds.</para> +<para>To specify an offset from the beginning of a PCP archive (in archive +mode) simply specify the offset as the <replaceable>duration</replaceable>. +For example, the following entry retrieves the first sample of data at +exactly 30 minutes from the beginning of a PCP archive.</para> +<para><literallayout class="monospaced">-S 30min </literallayout></para> +<para>To specify an offset from the end of a PCP archive, prefix the +<replaceable>duration</replaceable> with a minus sign. In this case, the first sample +time precedes the end of archived data by the given <replaceable>duration</replaceable>. +For example, the following entry retrieves the first sample +exactly one hour preceding the last sample in a PCP archive.</para> +<para><literallayout class="monospaced">-S -1hour </literallayout></para> +<para>To specify the calendar date and time (local time in the reporting +timezone) for the first sample, use the <literal>ctime(3)</literal> syntax +preceded by an “at” sign (@). For example, the following entry +specifies the date and time to be used.</para> +<para><literallayout class="monospaced">-S '@ Mon Mar 4 13:07:47 2013' </literallayout></para> +<para>Note that this format corresponds to the output format of the +<command>date</command> command for easy “cut and paste.” However, +be sure to enclose the string in quotes so it is preserved as a single +argument for the PCP tool.</para> +<para>For more complete information on the date and time syntax, see the <command>PCPIntro(1)</command> man page.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>-T </literal> <replaceable>duration</replaceable> </term> +<listitem><para>The terminate option may be used to request that the display +stop at the time designated by <replaceable>duration</replaceable>. By +default, the PCP tools keep sampling performance data indefinitely (in +real-time mode) or until the end of a PCP archive (in archive mode). The <literal>-T</literal> option may be used to specify an earlier time to terminate +sampling.</para> +<para>The interpretation for the <replaceable>duration</replaceable> argument +in a <literal>-T</literal> option is the same as for the <literal>-S</literal> +option, except for an unsigned time interval that is interpreted as being +an offset from the start of the time window as defined by the default +(now for real time, else start of archive) or by a <literal>-S</literal> +option. For example, these options define a time window that spans 45 +minutes, after an initial offset (or delay) of 1 hour:<literallayout class="monospaced">-S 1hour -T 45mins</literallayout></para> +</listitem></varlistentry> +<varlistentry> +<term><literal>-O </literal> <replaceable>duration</replaceable></term> +<listitem><para>By default, samples are fetched from the start time (see +the description of the <literal>-S</literal> option) to the terminate +time (see the description of the <literal>-T</literal> option). The offset <literal>-O</literal> option allows the specification of a time between the start +time and the terminate time where the tool should position its initial +sample time. This option is useful when initial attention is focused at +some point within a larger time window of interest, or when one PCP tool +wishes to launch another PCP tool with a common current point of time +within a shared time window.</para> +<para>The <replaceable>duration</replaceable> argument accepted by <literal>-O</literal> conforms to the same syntax and semantics as the <replaceable> +duration</replaceable> argument for <literal>-T</literal>. For example, +these options specify that the initial position should be the end of the +time window:<literallayout class="monospaced">-O -0 </literallayout></para> +<para>This is most useful with the <command>pmchart</command> command +to display the tail-end of the history up to the end of the time window. +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>-A </literal> <replaceable>alignment</replaceable></term> +<listitem><para>By default, performance data samples do not necessarily +happen at any natural unit of measured time. The <literal>-A</literal> +switch may be used to force the initial sample to be on the specified +<replaceable>alignment</replaceable>. For example, these three options specify alignment +on seconds, half hours, and whole hours:<literallayout class="monospaced">-A 1sec +-A 30min +-A 1hour</literallayout></para> +<para>The <literal>-A</literal> option advances the time to achieve the +desired alignment as soon as possible after the start of the time window, +whether this is the default window, or one specified with some combination +of <literal>-A</literal> and <literal>-O</literal> command line options. +</para> +</listitem></varlistentry> +</variablelist> +<para>Obviously the time window may be overspecified by using multiple +options from the set <literal>-t</literal>, <literal>-s</literal>, <literal>-S</literal>, <literal>-T</literal>, <literal>-A</literal>, and <literal>-O</literal>. Similarly, the time window may shrink to nothing by injudicious +choice of options.</para> +<para>In all cases, the parsing of these options applies heuristics guided +by the principal of “least surprise”; the time window is always +well-defined (with the end never earlier than the start), but may shrink +to nothing in the extreme.</para> +</section> +<section id="id5195323"> + +<title>Timezone Options</title> +<para><indexterm id="ITch03-12"><primary>timezone options</primary></indexterm>All +utilities that report time of day use the local timezone by default. The +following timezone options are available:</para> +<variablelist> +<varlistentry> +<term><literal>-z</literal></term> +<listitem><para>Forces times to be reported in the timezone of the host +that provided the metric values (the PCP collector host). When used in +conjunction with <literal>-a</literal> and multiple archives, the convention +is to use the timezone from the first named archive.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>-Z </literal> <replaceable>timezone</replaceable> </term> +<listitem><para><indexterm id="IG31371888135"><primary>environ man page</primary></indexterm>Sets +the TZ variable to a timezone string, as defined in <command>environ(7)</command>, +for example, <literal>-Z UTC</literal> for universal time.</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +<section id="LE61303-PARENT"> + +<title>PCP Environment Variables</title> +<para><indexterm id="ITch03-14"><primary>PCP</primary><secondary>environment +variables</secondary></indexterm><indexterm id="IG31371888136"><primary>environment variables +</primary></indexterm><indexterm id="IG31371888137"><primary>${PCP_DIR}/etc/pcp.conf file</primary> +</indexterm><indexterm id="IG31371888138"><primary>/etc/pcp.env file</primary></indexterm><indexterm id="IG31371888139"> +<primary>pmGetConfig function</primary></indexterm>When you are using +PCP tools and utilities and are calling PCP library functions, a standard +set of defined environment variables are available in the <filename>${PCP_DIR}/etc/pcp.conf</filename> +file. These variables are generally used to specify the location of various +PCP pieces in the file system and may be loaded into shell scripts by +sourcing the <filename>${PCP_DIR}/etc/pcp.env</filename> shell script. They may +also be queried by C, C++, perl and python programs using the +<command>pmGetConfig</command> library function. +If a variable is already defined in the +environment, the values in the <filename>pcp.conf</filename> file do not +override those values; that is, the values in <filename>pcp.conf</filename> +serve only as installation defaults. For additional information, see the <command>pcp.conf(5)</command>, <command>pcp.env(5)</command>, and <command>pmGetConfig(3)</command> +man pages.</para> +<para>The following environment variables are recognized by PCP (these +definitions are also available on the <command>PCPIntro(1)</command> man page):</para> +<variablelist condition="sgi_termlength:nextline"> +<varlistentry> +<term><literal>PCP_COUNTER_WRAP</literal></term> +<listitem><para><indexterm id="ITch03-15"><primary>PCP_COUNTER_WRAP variable +</primary></indexterm>Many of the performance metrics exported from PCP +agents expect that counters increase monotonically. Under some circumstances, +one value of a metric may be smaller than the previously fetched value. +This can happen when a counter of finite precision overflows, when the +PCP agent has been reset or restarted, or when the PCP agent exports values +from an underlying instrumentation that is subject to asynchronous discontinuity. +</para> +<para>If set, the <literal>PCP_COUNTER_WRAP</literal> environment variable +indicates that all such cases of a decreasing counter should be treated +as a counter overflow; and hence the values are assumed to have wrapped +once in the interval between consecutive samples. Counter wrapping was +the default in versions before the PCP release 1.3.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PCP_STDERR</literal></term> +<listitem><para><indexterm id="ITch03-18"><primary>PCP_STDERR variable +</primary></indexterm><indexterm id="IG31371888140"><primary>pmprintf tool</primary></indexterm><indexterm id="IG31371888141"> +<primary>pmconfirm command</primary><secondary>error messages</secondary> +</indexterm>Specifies whether <command>pmprintf()</command> error messages +are sent to standard error, an <literal>pmconfirm</literal> dialog box, +or to a named file; see the <command>pmprintf(3)</command> +man page. Messages go to standard error if <literal>PCP_STDERR</literal> +is unset or set without a value. If this variable is set to <literal>DISPLAY</literal>, then messages go to an <literal>pmconfirm</literal> +dialog box; see the <command>pmconfirm(1)</command> man page. +Otherwise, the value of <literal>PCP_STDERR</literal> is assumed to be +the name of an output file.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PMCD_CONNECT_TIMEOUT</literal></term> +<listitem><para><indexterm id="ITch03-22"><primary>PMCD_CONNECT_TIMEOUT +variable</primary></indexterm><indexterm id="IG31371888143"><primary>PMCD</primary><secondary> +PMCD_CONNECT_TIMEOUT variable</secondary></indexterm>When attempting to +connect to a remote PMCD on a system that is booting or at the other end +of a slow network link, some PMAPI routines could potentially block for +a long time until the remote system responds. These routines abort and +return an error if the connection has not been established after some +specified interval has elapsed. The default interval is 5 seconds. This +may be modified by setting this variable in the environment to a larger +number of seconds for the desired time out. This is most useful in cases +where the remote host is at the end of a slow network, requiring longer +latencies to establish the connection correctly.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PMCD_PORT</literal></term> +<listitem><para><indexterm id="ITch03-23"><primary>PMCD_PORT variable +</primary></indexterm><indexterm id="IG31371888144"><primary>PMCD</primary><secondary>PMCD_PORT +variable</secondary></indexterm><indexterm id="IG31371888145"><primary>TCP/IP</primary><secondary> +sockets</secondary></indexterm>This TCP/IP port is used by PMCD to create +the socket for incoming connections and requests. The default is port +number 44321, which you may override by setting this variable to a different +port number. If a non-default port is in effect when PMCD is started, +then every monitoring application connecting to that PMCD must also have +this variable set in its environment before attempting a connection.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PMCD_RECONNECT_TIMEOUT</literal></term> +<listitem><para><indexterm id="ITch03-24"><primary>PMCD_RECONNECT_TIMEOUT +variable</primary></indexterm><indexterm id="IG31371888146"><primary>PMCD</primary><secondary> +PMCD_RECONNECT_TIMEOUT variable</secondary></indexterm>When a monitor +or client application loses its connection to a PMCD, the connection may +be reestablished by calling the <command>pmReconnectContext(3)</command> +PMAPI function. However, attempts to reconnect are controlled by a back-off +strategy to avoid flooding the network with reconnection requests. By +default, the back-off delays are 5, 10, 20, 40, and 80 seconds for consecutive +reconnection requests from a client (the last delay is repeated for any +further attempts after the last delay in the list). Setting this environment +variable to a comma-separated list of positive integers redefines the +back-off delays. For example, setting the delays to <userinput>1,2</userinput> +will back off for 1 second, then back off every 2 seconds thereafter. +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PMCD_REQUEST_TIMEOUT</literal></term> +<listitem><para><indexterm id="ITch03-25"><primary>PMCD_REQUEST_TIMEOUT +variable</primary></indexterm><indexterm id="IG31371888147"><primary>PMCD</primary><secondary> +PMCD_REQUEST_TIMEOUT variable</secondary></indexterm>For monitor or client +applications connected to PMCD, there is a possibility of the application +hanging on a request for performance metrics or metadata or help text. +These delays may become severe if the system running PMCD crashes or the +network connection is lost or the network link is very slow. By setting +this environment variable to a real number of seconds, requests to PMCD +timeout after the specified number of seconds. The default behavior is +to wait 10 seconds for a response from every PMCD for all applications. +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PMLOGGER_PORT</literal></term> +<listitem><para><indexterm id="IG31371888148"><primary>PMLOGGER_PORT variable</primary></indexterm><indexterm id="IG31371888149"> +<primary>pmlogger tool</primary></indexterm><indexterm id="IG31371888150"><primary>pmlc tool +</primary><secondary>PMLOGGER_PORT variable</secondary></indexterm>This +environment variable may be used to change the base TCP/IP port number +used by <command>pmlogger</command> to create the socket to which <command>pmlc</command> +instances try to connect. The default base port number is 4330. +If used, this variable should be set in the environment before <command>pmlogger</command> +is executed. If <command>pmlc</command> and <command>pmlogger</command> +are on different hosts, then obviously <literal>PMLOGGER_PORT</literal> +must be set to the same value in both places.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>PMPROXY_PORT</literal></term> +<listitem><para><indexterm id="ITch03-30"><primary>PMPROXY_PORT variable +</primary></indexterm><indexterm id="IG31371888152"><primary>pmproxy port</primary></indexterm> +This environment variable may be used to change the base TCP/IP port number +used by <command>pmproxy</command> to create the socket to which proxied +clients connect, on their way to a distant <command>pmcd</command>.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="LE12082-PARENT"> + +<title>Running PCP Tools through a Firewall</title> +<para><indexterm id="IG31371888153"><primary>firewalls</primary></indexterm><indexterm id="IG31371888154"><primary> +TCP/IP</primary><secondary>collector and monitor hosts</secondary></indexterm>In +some production environments, the Performance Co-Pilot (PCP) monitoring +hosts are on one side of a TCP/IP firewall, and the PCP collector hosts +may be on the other side.</para> +<para><indexterm id="IG31371888155"><primary>PROXY protocol</primary></indexterm><indexterm id="IG31371888156"> +<primary>pmproxy tool</primary><secondary>TCP/IP firewall</secondary> +</indexterm><indexterm id="IG31371888157"><primary>PMCD</primary><secondary>TCP/IP firewall +</secondary></indexterm><indexterm id="IG31371888158"><primary>pmlogger tool</primary><secondary> +TCP/IP firewall</secondary></indexterm><indexterm id="IG31371888159"><primary>pmlc tool</primary> +<secondary>TCP/IP firewall</secondary></indexterm><indexterm id="IG31371888160"><primary> +PMCD_PORT variable</primary></indexterm><indexterm id="IG31371888161"><primary>PMLOGGER_PORT +variable</primary></indexterm>If the firewall service sits between the +monitor and collector tools, the <literal>pmproxy</literal> service may +be used to perform both packet forwarding and DNS proxying through the +firewall; see the <command>pmproxy(1)</command> +man page. Otherwise, it is necessary to arrange for packet +forwarding to be enabled for those TCP/IP ports used by PCP, namely 44321 +(or the value of the <literal>PMCD_PORT</literal> environment variable) +for connections to PMCD.</para> +<section id="id5196469"> + +<title>The <command>pmproxy</command> service</title> +<para>The <command>pmproxy</command> service allows PCP clients running on +hosts located on one side of a firewall to monitor remote +hosts on the other side. The basic connection syntax is as +follows, where <replaceable>tool</replaceable> is an arbitrary PCP application, +typically a monitoring tool:</para> +<literallayout class="monospaced">pmprobe -h remotehost@proxyhost</literallayout> +<para>This extended host specification syntax is part of a larger set of +available extensions to the basic host naming syntax - refer to the +<command>PCPIntro(1)</command> man page for further details.</para> +</section> +</section> +<section id="LE17322-PARENT"> + +<title>Transient Problems with Performance Metric Values +</title> +<para><indexterm id="IG31371888164"><primary>transient problems</primary></indexterm>Sometimes +the values for a performance metric as reported by a PCP tool appear to +be incorrect. This is typically caused by transient conditions such as +metric wraparound or time skew, described below. These conditions result +from design decisions that are biased in favor of lightweight protocols +and minimal resource demands for PCP components.</para> +<para>In all cases, these events are expected to occur infrequently, and +should not persist beyond a few samples.</para> +<section id="id5196702"> + +<title>Performance Metric Wraparound</title> +<para><indexterm id="ITch03-32"><primary>performance metric wraparound +</primary></indexterm><indexterm id="IG31371888165"><primary>PCP_COUNTER_WRAP variable</primary> +</indexterm>Performance metrics are usually expressed as numbers with +finite precision. For metrics that are cumulative counters of events or +resource consumption, the value of the metric may occasionally overflow +the specified range and wraparound to zero.</para> +<para>Because the value of these counter metrics is computed from the +rate of change with respect to the previous sample, this may result in +a transient condition where the rate of change is an unknown value. If +the <literal>PCP_COUNTER_WRAP</literal> environment variable is set, this +condition is treated as an overflow, and speculative rate calculations +are made. In either case, the correct rate calculation for the metric +returns with the next sample.</para> +</section> +<section id="id5196749"> + +<title>Time Dilation and Time Skew</title> +<para><indexterm id="ITch03-33"><primary>time dilation</primary></indexterm>If +a PMDA is tardy in returning results, or the PCP monitoring tool is connected +to PMCD via a slow or congested network, an error might be introduced +in rate calculations due to a difference between the time the metric was +sampled and the time PMCD sends the result to the monitoring tool.</para> +<para>In practice, these errors are usually so small as to be insignificant, +and the errors are self-correcting (not cumulative) over consecutive samples. +</para> +<para>A related problem may occur when the system time is not synchronized +between multiple hosts, and the time stamps for the results returned from +PMCD reflect the skew in the system times. In this case, it is recommended +that NTP (network time protocol) be used to keep the system clocks on the +collector systems synchronized; +for information on NTP refer to the <command>ntpd(1)</command> man page.</para> +</section> +</section> +</chapter> + + + +<chapter id="LE38515-PARENT"> + +<title>Monitoring System Performance</title> +<para><indexterm id="IG31371888166"><primary>monitoring system performance</primary></indexterm><indexterm id="IG31371888167"> +<primary>performance monitoring</primary></indexterm><indexterm id="IG31371888168"><primary> +man command</primary><secondary>usage</secondary></indexterm><indexterm id="Z1033415772tls"> +<primary>pmchart tool</primary><secondary>man example</secondary></indexterm>This +chapter describes the performance monitoring tools available in Performance +Co-Pilot (PCP). This product provides a group of commands and tools for measuring +system performance. Each tool is described completely by its own man page. +The man pages are accessible through the <command>man</command> command. For +example, the man page for the tool <command>pmdumptext</command> is viewed +by entering the following command:</para> +<literallayout class="monospaced"><userinput>man pmdumptext</userinput></literallayout> +<para>The following major sections are covered in this chapter:</para> +<itemizedlist> +<listitem id="Z930615099sdc"><para><xref linkend="LE91266-PARENT"/>, discusses <command>pmstat</command>, +a utility that provides a periodic one-line summary of system performance.</para> +</listitem> +<listitem><para><xref linkend="Z926977852sdc"/>, discusses <command>pmdumptext</command>, +a utility that shows the current values for named performance metrics.</para> +</listitem> +<listitem><para><xref linkend="LE35315-PARENT"/>, describes <command>pmval</command>, +a utility that displays performance metrics in a textual format.</para> +</listitem> +<listitem><para><xref linkend="LE60452-PARENT"/>, describes <command>pminfo</command>, +a utility that displays information about performance metrics. +</para> +</listitem> +<listitem><para><indexterm id="IG31371888169"><primary>pmstore tool</primary><secondary>setting +metric values</secondary></indexterm><xref linkend="LE10170-PARENT"/>, describes +the use of the <command>pmstore</command> utility to arbitrarily set or reset +selected performance metric values.</para> +</listitem></itemizedlist> +<para><indexterm id="IG31371888170"><primary>text-based tools</primary></indexterm><indexterm id="IG31371888171"> +<primary>2D tools</primary></indexterm>The following sections describe the +various graphical and text-based PCP tools used to monitor local or remote +system performance.</para> +<section id="LE91266-PARENT"> + +<title>The <command>pmstat</command> Command</title> +<para><indexterm id="ITch04-20"><primary>pmstat tool</primary><secondary> +description</secondary></indexterm> The <command>pmstat</command> command +provides a periodic, one-line summary of system performance. This command +is intended to monitor system performance at the highest level, after which +other tools may be used for examining subsystems to observe potential performance +problems in greater detail. After entering the <command>pmstat</command> +command, you see output similar to the following, with successive lines appearing +periodically:</para> +<literallayout class="monospaced"><userinput>pmstat</userinput> +@ Thu Aug 15 09:25:56 2013 + loadavg memory swap io system cpu + 1 min swpd free buff cache pi po bi bo in cs us sy id + 1.29 833960 5614m 144744 265824 0 0 0 1664 13K 23K 6 7 81 + 1.51 833956 5607m 144744 265712 0 0 0 1664 13K 24K 5 7 83 + 1.55 833956 5595m 145196 271908 0 0 14K 1056 13K 24K 7 7 74</literallayout> +<para>An additional line of output is added every five seconds. The +<literal>-t </literal><replaceable>interval</replaceable> option may be +used to vary the update interval (i.e. the sampling interval).</para> +<para>The output from <command>pmstat</command> is directed to standard output, +and the columns in the report are interpreted as follows:</para> +<variablelist> +<varlistentry> +<term><literal>loadavg</literal></term> +<listitem><para>The 1-minute load average (runnable processes).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>memory</literal></term> +<listitem><para>The swpd column indicates average swap space used during the +interval (all columns reported in Kbytes unless otherwise indicated). +The <literal>free</literal> column indicates average free memory during the +interval. The <literal>buff</literal> column indicates average buffer memory +in use during the interval. The <literal>cache</literal> column indicates +average cached memory in use during the interval.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>swap</literal></term> +<listitem><para>Reports the average number of pages that are paged-in +(<literal>pi</literal>) and paged-out (<literal>po</literal>) per +second during the interval. +It is normal for the paged-in values to be non-zero, but the system is +suffering memory stress if the paged-out values are non-zero over an +extended period.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>io</literal></term> +<listitem><para>The <literal>bi</literal> and <literal>bo</literal> columns +indicate the average rate per second of block input and block output +operations respectfully, during the interval. +These rates are independent of the I/O block size. +If the values become large, they are reported as thousands of operations per +second (K suffix) or millions of operations per second (M suffix).</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>system</literal></term> +<listitem><para> +Context switch rate (<literal>cs</literal>) and interrupt rate (<literal>in</literal>). +Rates are expressed as average operations per second during the interval. +Note that the interrupt rate is normally at least HZ (the clock interrupt rate, +and <literal>kernel.all.hz</literal> metric) interrupts per second.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>cpu</literal></term> +<listitem><para>Percentage of CPU time spent executing user code (<literal>us</literal>), +system and interrupt code (<literal>sy</literal>), idle loop (<literal>id</literal>).</para> +</listitem></varlistentry> +</variablelist> +<para>As with most PCP utilities, real-time metric, and archive logs are interchangeable. +</para> +<para>For example, the following command uses a local system PCP archive log +<replaceable>20130731</replaceable> and the timezone of the host (<literal>smash</literal>) +from which performance metrics in the archive were collected:</para> +<literallayout class="monospaced"><userinput>pmstat -a </userinput><replaceable>${PCP_LOG_DIR}/pmlogger/smash/20130731</replaceable> <userinput>-t 2hour -A 1hour -z</userinput> +Note: timezone set to local timezone of host "smash" +@ Wed Jul 31 10:00:00 2013 + loadavg memory swap io system cpu + 1 min swpd free buff cache pi po bi bo in cs us sy id + 3.90 24648 6234m 239176 2913m ? ? ? ? ? ? ? ? ? + 1.72 24648 5273m 239320 2921m 0 0 4 86 11K 19K 5 5 84 + 3.12 24648 5194m 241428 2969m 0 0 0 84 10K 19K 5 5 85 + 1.97 24644 4945m 244004 3146m 0 0 0 84 10K 19K 5 5 84 + 3.82 24640 4908m 244116 3147m 0 0 0 83 10K 18K 5 5 85 + 3.38 24620 4860m 244116 3148m 0 0 0 83 10K 18K 5 4 85 + 2.89 24600 4804m 244120 3149m 0 0 0 83 10K 18K 5 4 85 +pmFetch: End of PCP archive log</literallayout> +<para>For complete information on <literal>pmstat</literal> usage and command +line options, see the <command>pmstat(1)</command> man page. +</para> +</section> +<section id="Z926977852sdc"> + +<title>The <command>pmdumptext</command> Command</title> +<para><indexterm id="IG31371888172"><primary>pmdumptext tool</primary><secondary>description +</secondary></indexterm>The <command>pmdumptext</command> command displays +performance metrics in ASCII tables, suitable for export into databases or +report generators. It is a flexible command. For example, the following command +provides continuous memory statistics on a host named <literal>surf</literal>: +</para> +<literallayout class="monospaced"><userinput>pmdumptext -Ximu -h </userinput><userinput>surf</userinput><userinput> -f '%H:%M:%S' xfs.buffer</userinput> +[ 1] xfs.buffer.get +[ 2] xfs.buffer.create +[ 3] xfs.buffer.get_locked +[ 4] xfs.buffer.get_locked_waited +[ 5] xfs.buffer.busy_locked +[ 6] xfs.buffer.miss_locked +[ 7] xfs.buffer.page_retries +[ 8] xfs.buffer.page_found +[ 9] xfs.buffer.get_read + + Column 1 2 3 4 5 6 7 8 9 + Metric get create locked waited locked locked etries _found t_read + Units c/s c/s c/s c/s c/s c/s c/s c/s c/s +10:13:23 ? ? ? ? ? ? ? ? ? +10:13:24 0.16K 9.00 0.15K 5.00 0.00 0.00 0.00 12.00 9.00 +10:13:25 1.21K 38.00 1.17K 15.00 0.00 0.00 0.00 62.01 38.00 +10:13:26 5.80K 0.12K 5.69K 41.99 0.00 0.00 0.00 0.19K 0.12K</literallayout> +<para>See the <command>pmdumptext(1)</command> man page for more +information.</para> +</section> +<section id="LE35315-PARENT"> + +<title>The <command>pmval</command> Command</title> +<para><indexterm id="ITch04-23"><primary>pmval tool</primary><secondary>description +</secondary></indexterm> The <command>pmval</command> command dumps the current +values for the named performance metrics. For example, the following command +reports the value of performance metric <literal>proc.nprocs</literal> once +per second (by default), and produces output similar to this:</para> +<literallayout class="monospaced"><userinput>pmval proc.nprocs</userinput> +metric: proc.nprocs +host: localhost +semantics: discrete instantaneous value +units: none +samples: all +interval: 1.00 sec + 81 + 81 + 82 + 81</literallayout> +<para>In this example, the number of running processes was reported once per +second.</para> +<para>Where the semantics of the underlying performance metrics indicate that +it would be sensible, <command>pmval</command> reports the rate of change +or resource utilization.</para> +<para>For example, the following command reports idle processor utilization +for each of four CPUs on the remote host <literal>dove</literal>, each five +seconds apart, producing output of this form:</para> +<literallayout class="monospaced"><userinput>pmval -h dove -t 5sec -s 4 kernel.percpu.cpu.idle</userinput> +metric: kernel.percpu.cpu.idle +host: dove +semantics: cumulative counter (converting to rate) +units: millisec (converting to time utilization) +samples: 4 +interval: 5.00 sec + +cpu:1.1.0.a cpu:1.1.0.c cpu:1.1.1.a cpu:1.1.1.c + 1.000 0.9998 0.9998 1.000 + 1.000 0.9998 0.9998 1.000 + 0.8989 0.9987 0.9997 0.9995 + 0.9568 0.9998 0.9996 1.000 +</literallayout> +<para>Similarly, the following command reports disk I/O read rate every minute +for just the disk <literal>/dev/disk1</literal>, and produces output +similar to the following:</para> +<literallayout class="monospaced"><userinput>pmval -t 1min -i disk1 disk.dev.read</userinput> +metric: disk.dev.read +host: localhost +semantics: cumulative counter (converting to rate) +units: count (converting to count / sec) +samples: indefinite +interval: 60.00 sec + disk1 + 33.67 + 48.71 + 52.33 + 11.33 + 2.333 </literallayout> +<para>The <literal>-r</literal> flag may be used to suppress the rate calculation +(for metrics with counter semantics) and display the raw values of the metrics. +</para> +<para>In the example below, manipulation of the time within the archive is +achieved by the exchange of time control messages between <command>pmval</command> +and <command>pmtime</command>.</para> +<literallayout class="monospaced"><userinput>pmval -g -a ${PCP_LOG_DIR}/pmlogger/myserver/20130731 kernel.all.load</userinput></literallayout> +<para><indexterm id="IG31371888173"><primary>PCP Tutorials and Case Studies</primary><secondary>pmval command</secondary> +</indexterm>The <command>pmval</command> command is documented by the <command>pmval(1)</command> +man page, and annotated examples of the use of <command>pmval</command> can be found in +the <citetitle>PCP Tutorials and Case Studies</citetitle> companion document. +</para> +</section> +<section id="LE60452-PARENT"> + +<title>The <command>pminfo</command> Command</title> +<para><indexterm id="ITch04-25"><primary>pminfo tool</primary><secondary> +description</secondary></indexterm>The <command>pminfo</command> command displays +various types of information about performance metrics available through the +Performance Co-Pilot (PCP) facilities.</para> +<para>The <literal>-T</literal> option is extremely useful; it provides help +text about performance metrics:</para> +<literallayout class="monospaced"><userinput>pminfo -T mem.util.cached</userinput> +mem.util.cached +Help: +Memory used by the page cache, including buffered file data. +This is in-memory cache for files read from the disk (the pagecache) +but doesn't include SwapCached.</literallayout> +<para>The <literal>-t</literal> option displays the one-line help text associated +with the selected metrics. The <literal>-T</literal> option prints more verbose +help text.</para> +<para>Without any options, <command>pminfo</command> verifies that the specified +metrics exist in the namespace, and echoes those names. Metrics may be specified +as arguments to <command>pminfo</command> using their full metric names. For +example, this command returns the following response:</para> +<literallayout class="monospaced"><userinput>pminfo hinv.ncpu network.interface.total.bytes</userinput> +hinv.ncpu +network.interface.total.bytes </literallayout> +<para>A group of related metrics in the namespace may also be specified. +For example, to list all of the <literal>hinv</literal> metrics you would +use this command:</para> +<literallayout class="monospaced"><userinput>pminfo hinv</userinput> +hinv.physmem +hinv.pagesize +hinv.ncpu +hinv.ndisk +hinv.nfilesys +hinv.ninterface +hinv.nnode +hinv.machine +hinv.map.scsi +hinv.map.cpu_num +hinv.map.cpu_node +hinv.map.lvname +hinv.cpu.clock +hinv.cpu.vendor +hinv.cpu.model +hinv.cpu.stepping +hinv.cpu.cache +hinv.cpu.bogomips</literallayout> +<para>If no metrics are specified, <command>pminfo</command> displays the +entire collection of metrics. This can be useful for searching for metrics, +when only part of the full name is known. For example, this command returns +the following response:</para> +<literallayout class="monospaced"><userinput>pminfo | grep nfs</userinput> +nfs.client.calls +nfs.client.reqs +nfs.server.calls +nfs.server.reqs +nfs3.client.calls +nfs3.client.reqs +nfs3.server.calls +nfs3.server.reqs +nfs4.client.calls +nfs4.client.reqs +nfs4.server.calls +nfs4.server.reqs</literallayout> +<para>The <literal>-d</literal> option causes <command>pminfo</command> to +display descriptive information about metrics (refer to the <command>pmLookupDesc(3)</command> +man page for an explanation of this metadata information). +The following command and response show use of the <literal>-d</literal> option: +</para> +<literallayout class="monospaced"><userinput>pminfo -d proc.nprocs disk.dev.read filesys.free</userinput> +proc.nprocs + Data Type: 32-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff + Semantics: discrete Units: none + +disk.dev.read + Data Type: 32-bit unsigned int InDom: 60.1 0xf000001 + Semantics: counter Units: count + +filesys.free + Data Type: 64-bit unsigned int InDom: 60.5 0xf000005 + Semantics: instant Units: Kbyte</literallayout> +<para>The <literal>-f</literal> option to <command>pminfo</command> forces +the current value of each named metric to be fetched and printed. In the example +below, all metrics in the group <literal>hinv</literal> are selected:</para> +<literallayout class="monospaced"><userinput>pminfo -f hinv</userinput> +hinv.physmem + value 15701 + +hinv.pagesize + value 16384 + +hinv.ncpu + value 4 + +hinv.ndisk + value 6 + +hinv.nfilesys + value 2 + +hinv.ninterface + value 8 + +hinv.nnode + value 2 + +hinv.machine + value "IP35" + +hinv.map.cpu_num + inst [0 or "cpu:1.1.0.a"] value 0 + inst [1 or "cpu:1.1.0.c"] value 1 + inst [2 or "cpu:1.1.1.a"] value 2 + inst [3 or "cpu:1.1.1.c"] value 3 + +hinv.map.cpu_node + inst [0 or "node:1.1.0"] value "/dev/hw/module/001c01/slab/0/node" + inst [1 or "node:1.1.1"] value "/dev/hw/module/001c01/slab/1/node" + +hinv.cpu.clock + inst [0 or "cpu:1.1.0.a"] value 800 + inst [1 or "cpu:1.1.0.c"] value 800 + inst [2 or "cpu:1.1.1.a"] value 800 + inst [3 or "cpu:1.1.1.c"] value 800 + +hinv.cpu.vendor + inst [0 or "cpu:1.1.0.a"] value "GenuineIntel" + inst [1 or "cpu:1.1.0.c"] value "GenuineIntel" + inst [2 or "cpu:1.1.1.a"] value "GenuineIntel" + inst [3 or "cpu:1.1.1.c"] value "GenuineIntel" + +hinv.cpu.model + inst [0 or "cpu:1.1.0.a"] value "0" + inst [1 or "cpu:1.1.0.c"] value "0" + inst [2 or "cpu:1.1.1.a"] value "0" + inst [3 or "cpu:1.1.1.c"] value "0" + +hinv.cpu.stepping + inst [0 or "cpu:1.1.0.a"] value "6" + inst [1 or "cpu:1.1.0.c"] value "6" + inst [2 or "cpu:1.1.1.a"] value "6" + inst [3 or "cpu:1.1.1.c"] value "6" + +hinv.cpu.cache + inst [0 or "cpu:1.1.0.a"] value 0 + inst [1 or "cpu:1.1.0.c"] value 0 + inst [2 or "cpu:1.1.1.a"] value 0 + inst [3 or "cpu:1.1.1.c"] value 0 + +hinv.cpu.bogomips + inst [0 or "cpu:1.1.0.a"] value 1195.37 + inst [1 or "cpu:1.1.0.c"] value 1195.37 + inst [2 or "cpu:1.1.1.a"] value 1195.37 + inst [3 or "cpu:1.1.1.c"] value 1195.37</literallayout> +<para>The <literal>-h</literal> option directs <command>pminfo</command> to +retrieve information from the specified host. If the metric has an instance +domain, the value associated with each instance of the metric is printed: +</para> +<literallayout class="monospaced"><userinput>pminfo -h dove -f filesys.mountdir</userinput> +filesys.mountdir + inst [0 or "/dev/xscsi/pci00.01.0/target81/lun0/part3"] value "/" + inst [1 or "/dev/xscsi/pci00.01.0/target81/lun0/part1"] value "/boot/efi"</literallayout> +<para><indexterm id="IG31371888174"><primary>PMID</primary><secondary>printing</secondary></indexterm>The <literal>-m</literal> option prints the Performance Metric Identifiers (PMIDs) of the +selected metrics. This is useful for finding out which PMDA supplies the metric. +For example, the output below identifies the PMDA supporting domain 4 (the +leftmost part of the PMID) as the one supplying information for the metric <literal>environ.extrema.mintemp</literal>:</para> +<literallayout class="monospaced">pminfo -m environ.extrema.mintemp +environ.extrema.mintemp PMID: 4.0.3 </literallayout> +<para>The <literal>-v</literal> option verifies that metric definitions in +the PMNS correspond with supported metrics, and checks that a value is available +for the metric. Descriptions and values are fetched, but not printed. Only +errors are reported.</para> +<para><indexterm id="IG31371888175"><primary>pminfo tool</primary><secondary>PCP Tutorials and Case Studies</secondary> +</indexterm><indexterm id="IG31371888176"><primary>PCP Tutorials and Case Studies</primary><secondary>pminfo command +</secondary></indexterm>Complete information on the <command>pminfo</command> +command is found in the <command>pminfo(1)</command> man page. +There are further examples of the use of <command>pminfo</command> in the +<citetitle>PCP Tutorials and Case Studies</citetitle>.</para> +</section> +<section id="LE10170-PARENT"> + +<title>The <command>pmstore</command> Command</title> +<para><indexterm id="ITch04-26"><primary>pmstore tool</primary><secondary> +description</secondary></indexterm>From time to time you may wish to change +the value of a particular metric. Some metrics are counters that may need +to be reset, and some are simply control variables for agents that collect +performance metrics. When you need to change the value of a metric for any +reason, the command to use is <command>pmstore</command>.</para> +<note><para>For obvious reasons, the ability to arbitrarily change the value +of a performance metric is not supported. Rather, PCP collectors selectively +allow some metrics to be modified in a very controlled fashion.</para> +</note> +<para>The basic syntax of the command is as follows:</para> +<literallayout class="monospaced">pmstore <replaceable>metricname</replaceable> <replaceable>value</replaceable> </literallayout> +<para>There are also command line flags to further specify the action. For +example, the <literal>-i</literal> option restricts the change to one or more +instances of the performance metric.</para> +<para>The <replaceable>value</replaceable> may be in one of several forms, +according to the following rules:</para> +<orderedlist><listitem><para>If the metric has an integer type, then +<replaceable>value</replaceable> should consist of an optional leading hyphen, followed +either by decimal digits or “0x” and some hexadecimal digits; “0X” +is also acceptable instead of “0x.”</para> +</listitem><listitem><para>If the metric has a floating point type, then +<replaceable>value</replaceable> should be in the form of an integer (described above), +a fixed point number, or a number in scientific notation.</para> +</listitem><listitem><para>If the metric has a string type, then +<replaceable>value</replaceable> is interpreted as a literal string of ASCII characters. +</para> +</listitem><listitem><para>If the metric has an aggregate type, then an attempt +is made to interpret <replaceable>value</replaceable> as an integer, a floating +point number, or a string. In the first two cases, the minimal word length +encoding is used; for example, “123” would be interpreted as a +four-byte aggregate, and “0x100000000” would be interpreted as +an eight-byte aggregate.</para> +</listitem></orderedlist> +<para>The following example illustrates the use of <command>pmstore</command> +to enable performance metrics collection in the <literal>txmon</literal> PMDA +(see <literal>${PCP_PMDAS_DIR}/txmon</literal> for the source code of the txmon +PMDA). When the metric <literal>txmon.control.level</literal> has the value +0, no performance metrics are collected. Values greater than 0 enable progressively +more verbose instrumentation.</para> +<literallayout class="monospaced"><userinput>pminfo -f txmon.count</userinput> +txmon.count +No value(s) available! +<userinput>pmstore txmon.control.level 1</userinput> +txmon.control.level old value=0 new value=1 +<userinput>pminfo -f txmon.count</userinput> +txmon.count + inst [0 or "ord-entry"] value 23 + inst [1 or "ord-enq"] value 11 + inst [2 or "ord-ship"] value 10 + inst [3 or "part-recv"] value 3 + inst [4 or "part-enq"] value 2 + inst [5 or "part-used"] value 1 + inst [6 or "b-o-m"] value 0</literallayout> +<para>For complete information on <command>pmstore</command> usage and syntax, +see the <command>pmstore(1)</command> man page.</para> +</section> +</chapter> + + +<chapter id="LE21414-PARENT"> + +<title>Performance Metrics Inference Engine</title> +<para><indexterm id="ITch06-0"><primary>pmie tool</primary><secondary>performance +metrics inference engine</secondary></indexterm><indexterm id="ITch06-1"> +<primary>tool options</primary></indexterm><indexterm id="ITch06-2"><primary> +Performance Metrics Inference Engine</primary><see>pmie tool</see></indexterm>The +Performance Metrics Inference Engine (<command>pmie</command>) is a tool that +provides automated monitoring of, and reasoning about, system performance +within the Performance Co-Pilot (PCP) framework.</para> +<para>The major sections in this chapter are as follows:</para> +<itemizedlist> +<listitem><para><xref linkend="LE41170-PARENT"/>, provides an introduction +to the concepts and design of <command>pmie</command>.</para> +</listitem> +<listitem><para><xref linkend="LE15993-PARENT"/>, describes the basic syntax +and usage of <command>pmie</command>.</para> +</listitem> +<listitem><para><xref linkend="LE90227-PARENT"/>, discusses the complete +<command>pmie</command> rule specification language.</para> +</listitem> +<listitem><para><xref linkend="LE60280-PARENT"/>, provides an example, covering +several common performance scenarios.</para> +</listitem> +<listitem><para><xref linkend="LE31514-PARENT"/>, presents some tips and techniques +for <command>pmie</command> rule development.</para> +</listitem> +<listitem><para><xref linkend="LE91221-PARENT"/>, presents some important information +on using <command>pmie</command>.</para> +</listitem> +<listitem><para><xref linkend="Z927039566sdc"/>, describes how to use the +<command>pmieconf</command> command to generate <command>pmie</command> rules.</para> +</listitem> +<listitem><para><xref linkend="Z927039824sdc"/>, provides support for running +<command>pmie</command> as a daemon.</para> +</listitem></itemizedlist> +<section id="LE41170-PARENT"> + +<title>Introduction to <command>pmie</command></title> +<para><indexterm id="ITch06-4"><primary>pmie tool</primary><secondary>automated +reasoning</secondary></indexterm>Automated reasoning within Performance Co-Pilot +(PCP) is provided by the Performance Metrics Inference Engine, (<command>pmie</command>), +which is an applied artificial intelligence application. +</para> +<para>The <command>pmie</command> tool accepts expressions describing adverse +performance scenarios, and periodically evaluates these against streams of +performance metric values from one or more sources. When an expression is +found to be true, <command>pmie</command> is able to execute arbitrary actions +to alert or notify the system administrator of the occurrence of an adverse +performance scenario. These facilities are very general, and are designed +to accommodate the automated execution of a mixture of generic and site-specific +performance monitoring and control functions.</para> +<para>The stream of performance metrics to be evaluated may be from one or +more hosts, or from one or more PCP archive logs. In the latter case, <command>pmie</command> +may be used to retrospectively identify adverse performance conditions.</para> +<para><indexterm id="IG31371888177"><primary>PCP</primary><secondary>pmie capabilities</secondary> +</indexterm><indexterm id="IG31371888178"><primary>PMAPI</primary><secondary>pmie capabilities +</secondary></indexterm>Using <command>pmie</command>, you can filter, interpret, +and reason about the large volume of performance data made available from PCP +collector systems or PCP archives.</para> +<para>Typical <command>pmie</command> uses include the following:</para> +<itemizedlist> +<listitem><para>Automated real-time monitoring of a host, a set of hosts, +or client-server pairs of hosts to raise operational alarms when poor performance +is detected in a production environment</para> +</listitem> +<listitem><para>Nightly processing of archive logs to detect and report performance +regressions, or quantify quality of service for service level agreements or management +reports, or produce advance warning of pending performance problems</para> +</listitem> +<listitem><para>Strategic performance management, for example, detection of +slightly abnormal to chronic system behavior, trend analysis, and capacity planning +</para> +</listitem></itemizedlist> +<para><indexterm id="IG31371888179"><primary>pmie tool</primary><secondary>language</secondary> +</indexterm>The <command>pmie</command> expressions are described in a language +with expressive power and operational flexibility. It includes the following +operators and functions:</para> +<itemizedlist> +<listitem><para>Generalized predicate-action pairs, where a predicate is a +logical expression over the available performance metrics, and the action +is arbitrary. Predefined actions include the following:</para> +<itemizedlist><listitem><para><indexterm id="IG31371888180"><primary>pmconfirm command</primary> +<secondary>visible alarm</secondary></indexterm>Launch a visible alarm with <literal>pmconfirm</literal>; see the <command>pmconfirm(1)</command> man page.</para> +</listitem><listitem><para><indexterm id="IG31371888181"><primary>syslog function</primary></indexterm><indexterm id="IG31371888182"> +<primary>system log file</primary></indexterm>Post an entry to the system log file; +see the <command>syslog(3)</command> man page.</para> +</listitem><listitem><para><indexterm id="IG31371888183"><primary>${PCP_LOG_DIR}/NOTICES file</primary> +</indexterm>Post an entry to the PCP noticeboard file <filename>${PCP_LOG_DIR}/NOTICES</filename>; +see the <command>pmpost(1)</command> man page.</para> +</listitem><listitem><para>Execute a shell command or script, for example, +to send e-mail, initiate a pager call, warn the help desk, and so on.</para> +</listitem><listitem><para>Echo a message on standard output; useful for scripts +that generate reports from retrospective processing of PCP archive logs.</para> +</listitem></itemizedlist> +</listitem> +<listitem><para>Arithmetic and logical expressions in a C-like syntax.</para> +</listitem> +<listitem><para>Expression groups may have an independent evaluation frequency, +to support both short-term and long-term monitoring.</para> +</listitem> +<listitem><para>Canonical scale and rate conversion of performance metric +values to provide sensible expression evaluation.</para> +</listitem> +<listitem><para>Aggregation functions of <literal>sum</literal>, <literal>avg</literal>, <literal>min</literal>, and <literal>max</literal>, that may +be applied to collections of performance metrics values clustered over multiple +hosts, or multiple instances, or multiple consecutive samples in time.</para> +</listitem> +<listitem><para>Universal and existential quantification, to handle expressions +of the form “for every....” and “at least one...”. +</para> +</listitem> +<listitem><para>Percentile aggregation to handle statistical outliers, such +as “for at least 80% of the last 20 samples, ...”.</para> +</listitem> +<listitem><para>Macro processing to expedite repeated use of common subexpressions +or specification components.</para> +</listitem> +<listitem><para>Transparent operation against either live-feeds of performance +metric values from PMCD on one or more hosts, or against PCP archive logs +of previously accumulated performance metric values.</para> +</listitem></itemizedlist> +<para>The power of <command>pmie</command> may be harnessed to automate the +most common of the deterministic system management functions that are responses +to changes in system performance. For example, disable a batch stream if the +DBMS transaction commit response time at the ninetieth percentile goes over +two seconds, or stop accepting uploads and send e-mail to the <replaceable>sysadmin</replaceable> +alias if free space in a storage system falls below five percent.</para> +<para>Moreover, the power of <command>pmie</command> can be directed towards +the exceptional and sporadic performance problems. For example, if a network +packet storm is expected, enable IP header tracing for ten seconds, and send +e-mail to advise that data has been collected and is awaiting analysis. Or, +if production batch throughput falls below 50 jobs per minute, activate a pager +to the systems administrator on duty.</para> +<para><indexterm id="IG31371888184"><primary>pmie tool</primary><secondary>customization</secondary> +</indexterm><indexterm id="IG31371888185"><primary>pmieconf tool</primary><secondary>customization +</secondary></indexterm>Obviously, <command>pmie</command> customization is +required to produce meaningful filtering and actions in each production environment. +The <command>pmieconf</command> tool provides a convenient customization method, +allowing the user to generate parameterized <command>pmie</command> rules +for some of the more common performance scenarios.</para> +</section> +<section id="LE15993-PARENT"> + +<title>Basic <command>pmie</command> Usage</title> +<para><indexterm id="IG31371888186"><primary>pmie tool</primary><secondary>basic examples</secondary> +</indexterm>This section presents and explains some basic examples of <command>pmie</command> usage. +The <command>pmie</command> tool accepts the common +PCP command line arguments, as described in <xref linkend="LE94335-PARENT"/>. +In addition, <command>pmie</command> accepts the following command line arguments: +</para> +<variablelist condition="sgi_termlength:narrow"> +<varlistentry> +<term><literal>-d</literal></term> +<listitem><para>Enables interactive debug mode.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>-v</literal></term> +<listitem><para>Verbose mode: expression values are displayed.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>-V</literal></term> +<listitem><para>Verbose mode: annotated expression values are displayed.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>-W</literal></term> +<listitem><para>When-verbose mode: when a condition is true, the satisfying +expression bindings are displayed.</para> +</listitem></varlistentry> +</variablelist> +<para>One of the most basic invocations of this tool is this form:</para> +<literallayout class="monospaced"><userinput>pmie</userinput> <replaceable>filename</replaceable></literallayout> +<para>In this form, the expressions to be evaluated are read from <replaceable>filename</replaceable>. +In the absence of a given <replaceable>filename</replaceable>, +expressions are read from standard input, which may be your system keyboard.</para> +<section id="LE23271-PARENT"> + +<title><command>pmie</command> use of PCP services</title> +<para><indexterm id="ITch06-7"><primary>PCP</primary><secondary>pmie tool +</secondary></indexterm>Before you use <command>pmie</command>, it +is strongly recommended that you familiarize yourself with the concepts from +the <xref linkend="LE79836-PARENT"/>. The discussion in this section serves +as a very brief review of these concepts.</para> +<para><indexterm id="IG31371888187"><primary>pminfo tool</primary><secondary>pmie arguments</secondary> +</indexterm>PCP makes available thousands of performance metrics that +you can use when formulating expressions for <command>pmie</command> to evaluate. +If you want to find out which metrics are currently available on your system, +use this command:</para> +<literallayout class="monospaced"><userinput>pminfo</userinput> </literallayout> +<para>Use the <command>pmie</command> command line arguments to find out more +about a particular metric. In <xref linkend="Z983825969sdc"/>, to fetch new +metric values from host <literal>dove</literal>, you use the <literal>-f</literal> flag:</para> +<example id="Z983825969sdc"> +<title><command>pmie</command> +with the <literal>-f</literal> Option</title> +<literallayout class="monospaced"><userinput>pminfo -f -h dove disk.dev.total</userinput></literallayout> +<para>This produces the following response:</para> +<literallayout class="monospaced">disk.dev.total + inst [0 or "xscsi/pci00.01.0/target81/lun0/disc"] value 131233 + inst [4 or "xscsi/pci00.01.0/target82/lun0/disc"] value 4 + inst [8 or "xscsi/pci00.01.0/target83/lun0/disc"] value 4 + inst [12 or "xscsi/pci00.01.0/target84/lun0/disc"] value 4 + inst [16 or "xscsi/pci00.01.0/target85/lun0/disc"] value 4 + inst [18 or "xscsi/pci00.01.0/target86/lun0/disc"] value 4</literallayout> +</example> +<para>This reveals that on the host <literal>dove</literal>, the metric <literal>disk.dev.total</literal> has six instances, one for each disk on the system. +</para> +<para>Use the following command to request help text (specified with the <literal>-T</literal> flag) to provide more information about performance metrics: +</para> +<literallayout class="monospaced"><userinput>pminfo -T network.interface.in.packets</userinput></literallayout> +<para>The metadata associated with a performance metric is used by <command>pmie</command> +to determine how the value should be interpreted. You can examine +the descriptor that encodes the metadata by using the <literal>-d</literal> +flag for <command>pminfo</command>, as shown in <xref linkend="Z983826092sdc"/>: +</para> +<example id="Z983826092sdc"> +<title><command>pmie</command> +with the <literal>-d</literal> and <literal>-h</literal> Options</title> +<literallayout class="monospaced"><userinput>pminfo -d -h </userinput><replaceable>somehost </replaceable><userinput>mem.util.cached kernel.percpu.cpu.user</userinput></literallayout> +<para>In response, you see output similar to this:</para> +<literallayout class="monospaced">mem.util.cached + Data Type: 64-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff + Semantics: instant Units: Kbyte + +kernel.percpu.cpu.user + Data Type: 64-bit unsigned int InDom: 60.0 0xf000000 + Semantics: counter Units: millisec</literallayout> +</example> +<note><para><indexterm id="ITch06-8"><primary>PM_INDOM_NULL</primary></indexterm>A +cumulative counter such as <literal>kernel.percpu.cpu.user</literal> is automatically +converted by <command>pmie</command> into a rate (measured in events per second, +or count/second), while instantaneous values such as <literal>mem.util.cached</literal> +are not subjected to rate conversion. Metrics with an instance +domain (<literal>InDom</literal> in the <command>pminfo</command> output) +of <literal>PM_INDOM_NULL</literal> are singular and always produce one value +per source. However, a metric like <literal>kernel.percpu.cpu.user</literal> +has an instance domain, and may produce multiple values per source (in this +case, it is one value for each configured CPU).</para> +</note> +</section> +<section id="id5199666"> + +<title>Simple <command>pmie</command> Usage</title> +<para><indexterm id="ITch06-9"><primary>pmie tool</primary><secondary>examples +</secondary></indexterm><xref linkend="Z983823607sdc"/> directs the inference +engine to evaluate and print values (specified with the <literal>-v</literal> +flag) for a single performance metric (the simplest possible expression), +in this case <literal>disk.dev.total</literal>, collected from the local PMCD: +</para> +<example id="Z983823607sdc"> +<title><command>pmie</command> +with the <literal>-v</literal> Option</title> +<literallayout class="monospaced"><userinput>pmie -v</userinput> +<userinput>iops = disk.dev.total;</userinput> +<userinput>Ctrl+D</userinput> +iops: ? ? +iops: 14.4 0 +iops: 25.9 0.112 +iops: 12.2 0 +iops: 12.3 64.1 +iops: 8.594 52.17 +iops: 2.001 71.64</literallayout> +</example> +<para>On this system, there are two disk spindles, hence two values of the +expression <command>iops</command> per sample. Notice that the values for +the first sample are unknown (represented by the question marks [?] in the +first line of output), because rates can be computed only when at least two +samples are available. The subsequent samples are produced every ten seconds +by default. The second sample reports that during the preceding ten seconds +there was an average of 14.4 transfers per second on one disk and no transfers +on the other disk.</para> +<para>Rates are computed using time stamps delivered by PMCD. Due to unavoidable +inaccuracy in the actual sampling time (the sample interval is not exactly +10 seconds), you may see more decimal places in values than you expect. Notice, +however, that these errors do not accumulate but cancel each other out over +subsequent samples.</para> +<para>In <xref linkend="Z983823607sdc"/>, the expression to be evaluated was +entered using the keyboard, followed by the end-of-file character [<keycap>Ctrl</keycap>+<keycap>D</keycap>]. +Usually, it is more convenient to enter expressions +into a file (for example, <filename>myrules</filename>) and ask <command>pmie</command> +to read the file. Use this command syntax:</para> +<literallayout class="monospaced"><userinput>pmie -v myrules</userinput> </literallayout> +<para>Please refer to the <command>pmie(1)</command> man page +for a complete description of <command>pmie</command> command line options. +</para> +</section> +<section id="id5199841"> + +<title>Complex <command>pmie</command> Examples</title> +<para><indexterm id="ITch06-10"><primary>pmie tool</primary><secondary>examples +</secondary></indexterm>This section illustrates more complex <command>pmie</command> +expressions of the specification language. <xref linkend="LE90227-PARENT"/>, +provides a complete description of the <command>pmie</command> specification +language.</para> +<para>The following arithmetic expression computes the percentage of write +operations over the total number of disk transfers.</para> +<literallayout class="monospaced">(disk.all.write / disk.all.total) * 100; </literallayout> +<para>The <literal>disk.all</literal> metrics are singular, so this expression +produces exactly one value per sample, independent of the number of disk devices. +</para> +<note><para>If there is no disk activity,<literal> disk.all.total</literal> +will be zero and <command>pmie</command> evaluates this expression to be not +a number. When <literal>-v</literal> is used, any such values are displayed +as question marks.</para> +</note> +<para>The following logical expression has the value <literal>true</literal> +or <literal>false</literal> for each disk:</para> +<literallayout class="monospaced">disk.dev.total > 10 && +disk.dev.write > disk.dev.read; </literallayout> +<para>The value is true if the number of writes exceeds the number of reads, +and if there is significant disk activity (more than 10 transfers per second). +<xref linkend="Z983824038sdc"/> demonstrates a simple action:</para> +<example id="Z983824038sdc"> +<title>Printed <command>pmie</command> Output</title> +<literallayout class="monospaced">some_inst disk.dev.total > 60 + -> print "[%i] high disk i/o"; +</literallayout> +</example> +<para>This prints a message to the standard output whenever the total number +of transfers for some disk (<literal>some_inst</literal>) exceeds 60 transfers +per second. The <literal>%i</literal> (instance) in the message is replaced +with the name(s) of the disk(s) that caused the logical expression to be <literal>true</literal>.</para> +<para>Using <command>pmie</command> to evaluate the above expressions every +3 seconds, you see output similar to <xref linkend="Z983824037sdc"/>. +Notice the introduction of labels for each <command>pmie</command> expression.</para> +<example id="Z983824037sdc"> +<title>Labelled <command>pmie</command> Output</title> +<literallayout class="monospaced"><userinput>pmie -v -t 3sec</userinput> +<userinput>pct_wrt = (disk.all.write / disk.all.total) * 100;</userinput> +<userinput>busy_wrt = disk.dev.total > 10 &&</userinput> + <userinput>disk.dev.write > disk.dev.read;</userinput> +<userinput>busy = some_inst disk.dev.total > 60</userinput> + <userinput>-> print "[%i] high disk i/o ";</userinput> +<userinput>Ctrl+D</userinput> +pct_wrt: ? +busy_wrt: ? ? +busy: ? + +pct_wrt: 18.43 +busy_wrt: false false +busy: false + +Mon Aug 5 14:56:08 2012: [disk2] high disk i/o +pct_wrt: 10.83 +busy_wrt: false false +busy: true + +pct_wrt: 19.85 +busy_wrt: true false +busy: false + +pct_wrt: ? +busy_wrt: false false +busy: false + +Mon Aug 5 14:56:17 2012: [disk1] high disk i/o [disk2] high disk i/o +pct_wrt: 14.8 +busy_wrt: false false +busy: true</literallayout> +</example> +<para>The first sample contains unknowns, since all expressions depend on +computing rates. Also notice that the expression <literal>pct_wrt</literal> +may have an undefined value whenever all disks are idle, as the denominator +of the expression is zero. If one or more disks is busy, the expression <literal>busy</literal> is true, and the message from the <literal>print</literal> +in the action part of the rule appears (before the <literal>-v</literal> values). +</para> +</section> +</section> +<section id="LE90227-PARENT"> + +<title>Specification Language for <command>pmie</command></title> +<para><indexterm id="IG31371888188"><primary>pmie tool</primary><secondary>language</secondary> +</indexterm>This section describes the complete syntax of the <command>pmie</command> +specification language, as well as macro facilities and the issue +of sampling and evaluation frequency. The reader with a preference for learning +by example may choose to skip this section and go straight to the examples +in <xref linkend="LE60280-PARENT"/>.</para> +<para>Complex expressions are built up recursively from simple elements:</para> +<orderedlist><listitem><para>Performance metric values are obtained from PMCD +for real-time sources, otherwise from PCP archive logs.</para> +</listitem><listitem><para>Metrics values may be combined using arithmetic +operators to produce arithmetic expressions.</para> +</listitem><listitem><para>Arithmetic expressions may be compared using relational +operators to produce logical expressions.</para> +</listitem><listitem><para>Logical expressions may be combined using Boolean +operators, including powerful quantifiers.</para> +</listitem><listitem><para>Aggregation operators may be used to compute summary +expressions, for either arithmetic or logical operands.</para> +</listitem><listitem><para>The final logical expression may be used to initiate +a sequence of actions.</para> +</listitem></orderedlist> +<section id="LE51927-PARENT"> + +<title>Basic <command>pmie</command> Syntax</title> +<para><indexterm id="ITch06-11"><primary>pmie tool</primary><secondary>syntax +</secondary></indexterm>The <command>pmie</command> rule specification language +supports a number of basic syntactic elements.</para> +<section id="id5200293"> + +<title>Lexical Elements</title> +<para><indexterm id="IG31371888189"><primary>lexical elements</primary></indexterm>All <command>pmie</command> +expressions are composed of the following lexical elements: +</para> +<variablelist> +<varlistentry> +<term>Identifier</term> +<listitem><para>Begins with an alphabetic character (either upper or lowercase), +followed by zero or more letters, the numeric digits, and the special characters +period (<literal>.</literal>) and underscore (<literal>_</literal>), as shown +in the following example:<literallayout class="monospaced"><literal>x</literal>, <literal>disk.dev.total</literal> and <literal>my_stuff</literal></literallayout></para> +<para>As a special case, an arbitrary sequence of letters enclosed by apostrophes +(<literal>'</literal>) is also interpreted as an <replaceable>identifier</replaceable>; +for example:<literallayout class="monospaced">'vms$slow_response'</literallayout></para> +</listitem></varlistentry> +<varlistentry> +<term>Keyword</term> +<listitem><para>The aggregate operators, units, and predefined actions are +represented by keywords; for example, <literal>some_inst</literal>, <literal>print</literal>, and <literal>hour</literal>.</para> +</listitem></varlistentry> +<varlistentry> +<term>Numeric constant</term> +<listitem><para>Any likely representation of a decimal integer or floating +point number; for example, 124, 0.05, and -45.67</para> +</listitem></varlistentry> +<varlistentry> +<term>String constant</term> +<listitem><para>An arbitrary sequence of characters, enclosed by double quotation +marks (<literal>"x"</literal>).</para> +</listitem></varlistentry> +</variablelist> +<para>Within quotes of any sort, the backslash (<literal>\</literal>) may +be used as an escape character as shown in the following example:</para> +<literallayout class="monospaced">"A \"gentle\" reminder"</literallayout> +</section> +<section id="id5200461"> + +<title>Comments </title> +<para><indexterm id="IG31371888190"><primary>comments</primary></indexterm>Comments may be embedded +anywhere in the source, in either of these forms:</para> +<variablelist> +<varlistentry> +<term><literal>/* text */</literal></term> +<listitem><para>Comment, optionally spanning multiple lines, with no nesting +of comments.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>// text</literal></term> +<listitem><para>Comment from here to the end of the line.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5200514"> + +<title>Macros</title> +<para><indexterm id="IG31371888191"><primary>macros</primary></indexterm>When they are fully +specified, expressions in <command>pmie</command> tend to be verbose and repetitive. +The use of macros can reduce repetition and improve readability and modularity. +Any statement of the following form associates the macro name <literal>identifier</literal> with the given string constant.</para> +<literallayout class="monospaced"><literal>identifier = "<replaceable>string</replaceable>";</literal></literallayout> +<para>Any subsequent occurrence of the macro name <literal>identifier</literal> +is replaced by the <replaceable>string</replaceable> most recently associated +with a macro definition for <literal>identifier</literal>.</para> +<literallayout class="monospaced"><userinput>$</userinput><literal>identifier</literal> </literallayout> +<para>For example, start with the following macro definition:</para> +<literallayout class="monospaced">disk = "disk.all"; </literallayout> +<para>You can then use the following syntax:</para> +<literallayout class="monospaced">pct_wrt = ($disk.write / $disk.total) * 100;</literallayout> +<note><para>Macro expansion is performed before syntactic parsing; so macros +may only be assigned constant string values.</para> +</note> +</section> +<section id="id5200653"> + +<title>Units</title> +<para><indexterm id="IG31371888192"><primary>units</primary></indexterm>The inference engine +converts all numeric values to canonical units (seconds for time, bytes for +space, and events for count). To avoid surprises, you are encouraged to specify +the units for numeric constants. If units are specified, they are checked +for dimension compatibility against the metadata for the associated performance +metrics.</para> +<para>The syntax for a <literal>units</literal> specification is a sequence +of one or more of the following keywords separated by either a space or a +slash (<literal>/</literal>), to denote per: <literal>byte</literal>, <literal>KByte</literal>, <literal>MByte</literal>, <literal>GByte</literal>, <literal>TByte</literal>, <literal>nsec</literal>, <literal>nanosecond</literal>, <literal>usec</literal>, <literal>microsecond</literal>, <literal>msec</literal>, <literal>millisecond</literal>, <literal>sec</literal>, <literal>second</literal>, <literal>min</literal>, <literal>minute</literal>, <literal>hour</literal>, <literal>count</literal>, <literal>Kcount</literal>, <literal>Mcount</literal>, <literal>Gcount</literal>, or <literal>Tcount</literal>. Plural forms are also accepted. +</para> +<para>The following are examples of units usage:</para> +<literallayout class="monospaced">disk.dev.blktotal > 1 Mbyte / second; +mem.util.cached < 500 Kbyte;</literallayout> +<note><para>If you do not specify the units for numeric constants, it is assumed +that the constant is in the canonical units of seconds for time, bytes for +space, and events for count, and the dimensionality of the constant is assumed +to be correct. Thus, in the following expression, the <literal>500</literal> +is interpreted as 500 bytes.</para> +<literallayout class="monospaced">mem.util.cached < 500</literallayout> +</note> +</section> +</section> +<section id="LE88708-PARENT"> + +<title>Setting Evaluation Frequency</title> +<para><indexterm id="ITch06-12"><primary>pmie tool</primary><secondary>setting +evaluation frequency</secondary></indexterm><indexterm id="IG31371888193"><primary>evaluation +frequency</primary></indexterm>The identifier name <literal>delta</literal> +is reserved to denote the interval of time between consecutive evaluations +of one or more expressions. Set <literal>delta</literal> as follows:</para> +<literallayout class="monospaced">delta = <replaceable>number</replaceable> [<replaceable>units</replaceable>];</literallayout> +<para>If present, <literal>units</literal> must be one of the time units described +in the preceding section. If absent, <literal>units</literal> are assumed +to be <literal>seconds</literal>. For example, the following expression has +the effect that any subsequent expressions (up to the next expression that +assigns a value to <literal>delta</literal>) are scheduled for evaluation +at a fixed frequency, once every five minutes.</para> +<literallayout class="monospaced">delta = 5 min; </literallayout> +<para>The default value for <literal>delta</literal> may be specified using +the <literal>-t</literal> command line option; otherwise <literal>delta</literal> +is initially set to be 10 seconds.</para> +</section> +<section id="LE73508-PARENT"> + +<title><command>pmie</command> Metric Expressions</title> +<para><indexterm id="ITch06-13"><primary>pmie tool</primary><secondary>metric +expressions</secondary></indexterm><indexterm id="IG31371888194"><primary>PMNS</primary><secondary> +metric expressions</secondary></indexterm><indexterm id="IG31371888196"><primary> +PMCD</primary><secondary>collector host</secondary></indexterm>The performance +metrics namespace (PMNS) provides a means of naming performance metrics, +for example, <literal>disk.dev.read</literal>. +PCP allows an application to retrieve one or more values for a performance +metric from a designated source (a collector host running PMCD, or a PCP archive +log). To specify a single value for some performance metric requires the metric +name to be associated with all three of the following:</para> +<itemizedlist> +<listitem><para>A particular host (or source of metrics values)</para> +</listitem> +<listitem><para>A particular instance (for metrics with multiple values)</para> +</listitem> +<listitem><para>A sample time</para> +</listitem></itemizedlist> +<para>The permissible values for hosts are the range of valid hostnames as +provided by Internet naming conventions.</para> +<para><indexterm id="IG31371888197"><primary>PMDA</primary><secondary>instance names</secondary> +</indexterm>The names for instances are provided by the Performance Metrics +Domain Agents (PMDA) for the instance domain associated with the chosen performance +metric.</para> +<para>The sample time specification is defined as the set of natural numbers +0, 1, 2, and so on. A number refers to one of a sequence of sampling events, +from the current sample 0 to its predecessor 1, whose predecessor was 2, and +so on. This scheme is illustrated by the time line shown in <xref linkend="id5201070"/>. +</para> +<figure id="id5201070"><title>Sampling Time Line</title><mediaobject><imageobject><imagedata fileref="figures/sampling-timeline.svg"/></imageobject><textobject><phrase>Sampling Time Line</phrase></textobject></mediaobject></figure> +<para>Each sample point is assumed to be separated from its predecessor by +a constant amount of real time, the <literal>delta</literal>. The most recent +sample point is always zero. The value of <literal>delta</literal> may vary +from one expression to the next, but is fixed for each expression; for more +information on the sampling interval, see <xref linkend="LE88708-PARENT"/>. +</para> +<para>For <command>pmie</command>, a metrics expression is the name of a metric, +optionally qualified by a host, instance and sample time specification. Special +characters introduce the qualifiers: colon (<literal>:</literal>) for hosts, +hash or pound sign (<literal>#</literal>) for instances, and at (<literal>@</literal>) for sample times. The following expression refers to the previous +value (<literal>@1</literal>) of the counter for the disk read operations +associated with the disk instance <literal>#disk1</literal> on the host <literal>moomba</literal>.</para> +<literallayout class="monospaced">disk.dev.read :moomba #disk1 @1 </literallayout> +<para>In fact, this expression defines a point in the three-dimensional (3D) +parameter space of {<literal>host</literal>} x {<literal>instance</literal>} +x {<literal>sample time</literal>} as shown in <xref linkend="id5201194"/>. +</para> +<figure id="id5201194"><title>Three-Dimensional Parameter Space</title><mediaobject><imageobject><imagedata fileref="figures/parameter-space.svg"/></imageobject><textobject><phrase>Three-Dimensional Parameter Space</phrase></textobject></mediaobject></figure> +<para>A metric expression may also identify sets of values corresponding to +one-, two-, or three-dimensional slices of this space, according to the following +rules:</para> +<orderedlist><listitem><para>A metric expression consists of a PCP metric +name, followed by optional host specifications, followed by optional instance +specifications, and finally, optional sample time specifications.</para> +</listitem><listitem><para>A host specification consists of one or more host +names, each prefixed by a colon (<literal>:</literal>). For example: <literal>:indy :far.away.domain.com :localhost</literal></para> +</listitem><listitem><para>A missing host specification implies the default <command>pmie</command> +source of metrics, as defined by a <literal>-h</literal> option +on the command line, or the first named archive in an <literal>-a</literal> +option on the command line, or PMCD on the local host.</para> +</listitem><listitem><para>An instance specification consists of one or more +instance names, each prefixed by a hash or pound (<literal>#</literal>) sign. +For example: <literal>#eth0 #eth2</literal></para> +<para>Recall that you can discover the instance names for a particular metric, +using the <command>pminfo</command> command. See <xref linkend="LE23271-PARENT"/>. +</para> +<para>Within the <command>pmie</command> grammar, an instance name is an identifier. +If the instance name contains characters other than alphanumeric characters, +enclose the instance name in single quotes; for example, <literal>#'/boot' #'/usr'</literal></para> +</listitem><listitem><para>A missing instance specification implies all instances +for the associated performance metric from each associated <command>pmie</command> +source of metrics.</para> +</listitem><listitem><para>A sample time specification consists of either +a single time or a range of times. A single time is represented as an at (<literal>@</literal>) followed by a natural number. A range of times is an at (<literal>@</literal>), followed by a natural number, followed by two periods (<literal>..</literal>) followed by a second natural number. The ordering of the end +points in a range is immaterial. For example, <literal>@0..9</literal> specifies +the last 10 sample times.</para> +</listitem><listitem><para>A missing sample time specification implies the +most recent sample time.</para> +</listitem></orderedlist> +<para>The following metric expression refers to a three-dimensional set of +values, with two hosts in one dimension, five sample times in another, and +the number of instances in the third dimension being determined by the number +of configured disk spindles on the two hosts.</para> +<literallayout class="monospaced">disk.dev.read :foo :bar @0..4</literallayout> +</section> +<section id="LE59099-PARENT"> + +<title><command>pmie</command> Rate Conversion</title> +<para><indexterm id="ITch06-14"><primary>pmie tool</primary><secondary>rate +conversion</secondary></indexterm><indexterm id="IG31371888198"><primary>rate conversion</primary> +</indexterm>Many of the metrics delivered by PCP are cumulative counters. +Consider the following metric:</para> +<literallayout class="monospaced">disk.all.total </literallayout> +<para>A single value for this metric tells you only that a certain number +of disk I/O operations have occurred since boot time, and that information +may be invalid if the counter has exceeded its 32-bit range and wrapped. You +need at least two values, sampled at known times, to compute the recent rate +at which the I/O operations are being executed. The required syntax would +be this:</para> +<literallayout class="monospaced">(disk.all.total @0 - disk.all.total @1) / delta </literallayout> +<para>The accuracy of <literal>delta</literal> as a measure of actual inter-sample +delay is an issue. <command>pmie</command> requests samples, at intervals +of approximately <literal>delta</literal>, while the results exported from +PMCD are time stamped with the high-resolution system clock time when the +samples were extracted. For these reasons, a built-in and implicit rate conversion +using accurate time stamps is provided by <command>pmie</command> for performance +metrics that have counter semantics. For example, the following expression +is unconditionally converted to a rate by <command>pmie</command>.</para> +<literallayout class="monospaced">disk.all.total </literallayout> +</section> +<section id="id5201567"> + +<title><command>pmie</command> Arithmetic Expressions</title> +<para><indexterm id="ITch06-15"><primary>pmie tool</primary><secondary>arithmetic +expressions</secondary></indexterm><indexterm id="IG31371888199"><primary>arithmetic expressions +</primary></indexterm>Within <command>pmie</command>, simple arithmetic expressions +are constructed from metrics expressions (see <xref linkend="LE73508-PARENT"/>) +and numeric constants, using all of the arithmetic operators and precedence +rules of the C programming language.</para> +<para>All <command>pmie</command> arithmetic is performed in double precision. +</para> +<para><xref linkend="LE87294-PARENT"/>, describes additional operators that +may be used for aggregate operations to reduce the dimensionality of an arithmetic +expression.</para> +</section> +<section id="id5201630"> + +<title><command>pmie</command> Logical Expressions</title> +<para><indexterm id="ITch06-16"><primary>pmie tool</primary><secondary>logical +expressions</secondary></indexterm><indexterm id="IG31371888200"><primary>logical expressions +</primary></indexterm>A number of logical expression types are supported: +</para> +<itemizedlist> +<listitem><para>Logical constants</para> +</listitem> +<listitem><para>Relational expressions</para> +</listitem> +<listitem><para>Boolean expressions</para> +</listitem> +<listitem><para>Quantification operators</para> +</listitem></itemizedlist> +<section id="id5201707"> + +<title>Logical Constants</title> +<para><indexterm id="IG31371888201"><primary>logical constants</primary></indexterm>Like in the +C programming language, <command>pmie</command> interprets an arithmetic value +of zero to be false, and all other arithmetic values are considered true. +</para> +</section> +<section id="id5201731"> + +<title>Relational Expressions</title> +<para><indexterm id="IG31371888202"><primary>relational expressions</primary></indexterm>Relational +expressions are the simplest form of logical expression, in which values may +be derived from arithmetic expressions using <command>pmie</command> relational +operators. For example, the following is a relational expression that is true +or false, depending on the aggregate total of disk read operations per second +being greater than 50.</para> +<literallayout class="monospaced">disk.all.read > 50 count/sec</literallayout> +<para>All of the relational logical operators and precedence rules of the +C programming language are supported in <command>pmie</command>.</para> +<para>As described in <xref linkend="LE73508-PARENT"/>, arithmetic expressions +in <command>pmie</command> may assume set values. The relational operators +are also required to take constant, singleton, and set-valued expressions +as arguments. The result has the same dimensionality as the operands. Suppose +the rule in <xref linkend="Z983832287sdc"/> is given:</para> +<example id="Z983832287sdc"> +<title>Relational Expressions +</title> +<literallayout class="monospaced"><userinput>hosts = ":gonzo";</userinput> +<userinput>intfs = "#eth0 #eth2";</userinput> +<userinput>all_intf = network.interface.in.packets</userinput> + <userinput>$hosts $intfs @0..2 > 300 count/sec;</userinput></literallayout> +<para>Then the execution of <command>pmie</command> may proceed as follows: +</para> +<literallayout class="monospaced"><userinput>pmie -V uag.11</userinput> +all_intf: + gonzo: [eth0] ? ? ? + gonzo: [eth2] ? ? ? +all_intf: + gonzo: [eth0] false ? ? + gonzo: [eth2] false ? ? +all_intf: + gonzo: [eth0] true false ? + gonzo: [eth2] false false ? +all_intf: + gonzo: [eth0] true true false + gonzo: [eth2] false false false</literallayout> +</example> +<para>At each sample, the relational operator greater than (>) produces six +truth values for the cross-product of the <literal>instance</literal> and <literal>sample time</literal> dimensions.</para> +<para><xref linkend="LE97708-PARENT"/>, describes additional logical operators +that may be used to reduce the dimensionality of a relational expression. +</para> +</section> +<section id="id5201927"> + +<title>Boolean Expressions</title> +<para><indexterm id="IG31371888203"><primary>Boolean expressions</primary></indexterm>The regular +Boolean operators from the C programming language are supported: conjunction +(<literal>&&</literal>), disjunction (<literal>||</literal>) and negation +(<literal>!</literal>).</para> +<para>As with the relational operators, the Boolean operators accommodate +set-valued operands, and set-valued results.</para> +</section> +<section id="LE97708-PARENT"> + +<title>Quantification Operators</title> +<para><indexterm id="IG31371888204"><primary>quantification operators</primary></indexterm><indexterm id="IG31371888205"> +<primary>operators</primary></indexterm>Boolean and relational operators may +accept set-valued operands and produce set-valued results. In many cases, +rules that are appropriate for performance management require a set of truth +values to be reduced along one or more of the dimensions of hosts, instances, +and sample times described in <xref linkend="LE73508-PARENT"/>. +The <command>pmie</command> quantification operators perform this function.</para> +<para>Each quantification operator takes a one-, two-, or three-dimension +set of truth values as an operand, and reduces it to a set of smaller dimension, +by quantification along a single dimension. For example, suppose the expression +in the previous example is simplified and prefixed by <literal>some_sample</literal>, to produce the following expression:</para> +<literallayout class="monospaced"><userinput>intfs = "#eth0 #eth2";</userinput>  +<userinput>all_intf = some_sample network.interface.in.packets</userinput> + <userinput>$intfs @0..2 > 300 count/sec;</userinput></literallayout> +<para>Then the expression result is reduced from six values to two (one per +interface instance), such that the result for a particular instance will be +false unless the relational expression for the same interface instance is +true for at least one of the preceding three sample times.</para> +<para>There are existential, universal, and percentile quantification operators +in each of the <replaceable>host</replaceable>, <replaceable>instance</replaceable>, +and <replaceable>sample time</replaceable> dimensions to produce the nine +operators as follows:</para> +<variablelist> +<varlistentry> +<term><literal>some_host</literal></term> +<listitem><para>True if the expression is true for at least one <replaceable>host</replaceable> +for the same <replaceable>instance</replaceable> and <literal>sample time</literal>.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>all_host</literal></term> +<listitem><para>True if the expression is true for every <replaceable>host</replaceable> +for the same <replaceable>instance</replaceable> and <replaceable>sample time</replaceable>.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>N</replaceable><literal>%</literal><literal>_host</literal></term> +<listitem><para>True if the expression is true for at least <replaceable>N</replaceable>% +of the <replaceable>hosts</replaceable> for the same <replaceable>instance</replaceable> +and <replaceable>sample time</replaceable>.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>some_inst</literal></term> +<listitem><para>True if the expression is true for at least one <replaceable>instance</replaceable> +for the same <replaceable>host</replaceable> and <replaceable>sample time</replaceable>.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>all_instance</literal></term> +<listitem><para>True if the expression is true for every <replaceable>instance</replaceable> +for the same <replaceable>host</replaceable> and <replaceable>sample time</replaceable>.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>N</replaceable><literal>%</literal><literal>_instance</literal></term> +<listitem><para>True if the expression is true for at least <replaceable>N</replaceable>% +of the <replaceable>instances</replaceable> for the same <replaceable>host</replaceable> +and <replaceable>sample time</replaceable>.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>some_sample time</literal></term> +<listitem><para>True if the expression is true for at least one <replaceable>sample time</replaceable> +for the same <replaceable>host</replaceable> and <replaceable>instance</replaceable>.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>all_sample time</literal></term> +<listitem><para>True if the expression is true for every <replaceable>sample time</replaceable> +for the same <replaceable>host</replaceable> and <replaceable>instance</replaceable>.</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>N</replaceable><literal>%</literal><literal>_sample time</literal></term> +<listitem><para>True if the expression is true for at least <replaceable>N</replaceable>% +of the <replaceable>sample times</replaceable> for the same <replaceable>host</replaceable> +and <replaceable>instance</replaceable>.</para> +</listitem></varlistentry> +</variablelist> +<para>These operators may be nested. For example, the following expression +answers the question: “Are all hosts experiencing at least 20% of their +disks busy either reading or writing?”</para> +<literallayout class="monospaced">Servers = ":moomba :babylon"; +all_host ( + 20%_inst disk.dev.read $Servers > 40 || + 20%_inst disk.dev.write $Servers > 40 +); </literallayout> +<para>The following expression uses different syntax to encode the same semantics: +</para> +<literallayout class="monospaced">all_host ( + 20%_inst ( + disk.dev.read $Servers > 40 || + disk.dev.write $Servers > 40 + ) +);</literallayout> +<note><para>To avoid confusion over precedence and scope for the quantification +operators, use explicit parentheses.</para> +</note> +<para>Two additional quantification operators are available for the instance +dimension only, namely <literal>match_inst</literal> and <literal>nomatch_inst</literal>, that take a regular expression and a boolean expression. The result +is the boolean AND of the expression and the result of matching (or not matching) +the associated instance name against the regular expression.</para> +<para>For example, this rule evaluates error rates on various 10BaseT Ethernet +network interfaces (such as ecN, ethN, or efN):</para> +<literallayout class="monospaced">some_inst + match_inst "^(ec|eth|ef)" + network.interface.total.errors > 10 count/sec +-> syslog "Ethernet errors:" " %i"</literallayout> +</section> +</section> +<section id="id5202519"> + +<title><command>pmie</command> Rule Expressions</title> +<para><indexterm id="IG31371888206"><primary>rule expressions</primary></indexterm>Rule expressions +for <command>pmie</command> have the following syntax:</para> +<literallayout class="monospaced">lexpr -> <replaceable>actions</replaceable> ;</literallayout> +<para>The semantics are as follows:</para> +<itemizedlist> +<listitem><para>If the logical expression <literal>lexpr</literal> evaluates <literal>true</literal>, then perform the <replaceable>actions</replaceable> that follow. +Otherwise, do not perform the <replaceable>actions</replaceable>.</para> +</listitem> +<listitem><para>It is required that <literal>lexpr</literal> has a singular +truth value. Aggregation and quantification operators must have been applied +to reduce multiple truth values to a single value.</para> +</listitem> +<listitem><para>When executed, an <replaceable>action</replaceable> completes +with a success/failure status.</para> +</listitem> +<listitem><para>One or more <replaceable>actions</replaceable> may appear; +consecutive <replaceable>actions</replaceable> are separated by operators +that control the execution of subsequent <replaceable>actions</replaceable>, +as follows:</para> +<variablelist id="Z926963018sdc"> +<varlistentry> +<term><replaceable>action-1 </replaceable><literal>&</literal></term> +<listitem><para>Always execute subsequent actions (serial execution).</para> +</listitem></varlistentry> +<varlistentry> +<term><replaceable>action-1 </replaceable><userinput>|</userinput> </term> +<listitem><para>If <replaceable>action-1</replaceable> fails, execute subsequent +actions, otherwise skip the subsequent actions (alternation).</para> +</listitem></varlistentry> +</variablelist> +</listitem></itemizedlist> +<para>An <replaceable>action</replaceable> is composed of a keyword to identify +the action method, an optional <replaceable>time</replaceable> specification, +and one or more arguments.</para> +<para>A <replaceable>time</replaceable> specification uses the same syntax +as a valid time interval that may be assigned to <literal>delta</literal>, +as described in <xref linkend="LE88708-PARENT"/>. If the <replaceable>action</replaceable> +is executed and the <replaceable>time</replaceable> specification +is present, <command>pmie</command> will suppress any subsequent execution +of this <replaceable>action</replaceable> until the wall clock time has advanced +by <replaceable>time</replaceable>.</para> +<para>The arguments are passed directly to the action method.</para> +<para>The following action methods are provided:</para> +<variablelist> +<varlistentry> +<term><literal>shell</literal></term> +<listitem><para>The single argument is passed to the shell for execution. +This <replaceable>action</replaceable> is implemented using <literal>system</literal> in the background. The <replaceable>action</replaceable> does not +wait for the system call to return, and succeeds unless the fork fails.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>alarm</literal></term> +<listitem><para><indexterm id="IG31371888207"><primary>DISPLAY variable</primary></indexterm>A +notifier containing a time stamp, a single <replaceable>argument</replaceable> +as a message, and a <guilabel>Cancel</guilabel> button is +posted on the current display screen (as identified by the <literal>DISPLAY</literal> environment variable). Each alarm <replaceable>action</replaceable> +first checks if its notifier is already active. If there is an identical active +notifier, a duplicate notifier is not posted. The action succeeds unless the +fork fails.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>syslog</literal></term> +<listitem><para><indexterm id="IG31371888208"><primary>pmlogger tool</primary></indexterm><indexterm id="IG31371888209"> +<primary>syslog function</primary></indexterm>A message is written into the +system log. If the first word of the first argument is <literal>-p</literal>, +the second word is interpreted as the priority (see the <command>syslog(3)</command> +man page); the message tag is <literal>pcp-pmie</literal>. +The remaining argument is the message to be written to the system log. +This action always succeeds.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>print</literal></term> +<listitem><para><indexterm id="IG31371888210"><primary>time-stamped message</primary></indexterm>A +message containing a time stamp in <command>ctime(3)</command> format and the +argument is displayed out to standard output (<command>stdout</command>). +This action always succeeds.</para> +</listitem></varlistentry> +</variablelist> +<para>Within the argument passed to an action method, the following expansions +are supported to allow some of the context from the logical expression on +the left to appear to be embedded in the argument:</para> +<variablelist condition="sgi_termlength:narrow"> +<varlistentry> +<term><literal>%h</literal></term> +<listitem><para>The value of a <replaceable>host</replaceable> that makes +the expression true.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>%i</literal></term> +<listitem><para>The value of an <replaceable>instance</replaceable> that makes +the expression true.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>%v</literal></term> +<listitem><para>The value of a performance metric from the logical expression. +</para> +</listitem></varlistentry> +</variablelist> +<para><indexterm id="IG31371888211"><primary>pmie tool</primary><secondary>%-token</secondary> +</indexterm>Some ambiguity may occur in respect to which host, instance, or +performance metric is bound to a %-token. In most cases, the leftmost binding +in the top-level subexpression is used. You may need to use <command>pmie</command> +in the interactive debugging mode (specify the <literal>-d</literal> +command line option) in conjunction with the <literal>-W</literal> command +line option to discover which subexpressions contributes to the %-token bindings. +</para> +<para><xref linkend="Z983833504sdc"/> illustrates some of the options when +constructing rule expressions:</para> +<example id="Z983833504sdc"> +<title>Rule Expression Options +</title> +<literallayout class="monospaced">some_inst ( disk.dev.total > 60 ) + -> syslog 10 mins "[%i] busy, %v IOPS " & + shell 1 hour "echo \ + 'Disk %i is REALLY busy. Running at %v I/Os per second' \ + | Mail -s 'pmie alarm' sysadm"; </literallayout> +</example> +<para><indexterm id="IG31371888212"><primary>system log file</primary></indexterm>In this +case, <literal>%v</literal> and <literal>%i</literal> are both associated +with the instances for the metric <literal>disk.dev.total</literal> that make +the expression true. If more than one instance makes the expression true (more +than one disk is busy), then the argument is formed by concatenating the result +from each %-token binding. The text added to the system log file +might be as shown in <xref linkend="Z983833442sdc"/>:</para> +<example id="Z983833442sdc"> +<title>System Log Text</title> +<literallayout class="monospaced">Aug 6 08:12:44 5B:gonzo pcp-pmie[3371]: + [disk1] busy, 3.7 IOPS [disk2] busy, 0.3 IOPS</literallayout> +</example> +<note><para>When <command>pmie</command> is processing performance metrics +from a PCP archive log, the <replaceable>actions</replaceable> will be processed +in the expected manner; however, the action methods are modified to report +a textual facsimile of the <replaceable>action</replaceable> on the standard +output.</para> +</note> +<para>Consider the rule in <xref linkend="Z983833364sdc"/>:</para> +<example id="Z983833364sdc"> +<title>Standard Output</title> +<literallayout class="monospaced">delta = 2 sec; // more often for demonstration purposes +percpu = "kernel.percpu"; +// Unusual usr-sys split when some CPU is more than 20% in usr mode +// and sys mode is at least 1.5 times usr mode +// +cpu_usr_sys = some_inst ( + $percpu.cpu.sys > $percpu.cpu.user * 1.5 && + $percpu.cpu.user > 0.2 + ) -> alarm "Unusual sys time: " "%i "; </literallayout> +<para>When evaluated against an archive, the following output is generated +(the alarm action produces a message on standard output):</para> +<literallayout class="monospaced"><userinput>pmafm ${HOME}/f4 pmie cpu.head cpu.00</userinput> +alarm Wed Aug 7 14:54:48 2012: Unusual sys time: cpu0 +alarm Wed Aug 7 14:54:50 2012: Unusual sys time: cpu0 +alarm Wed Aug 7 14:54:52 2012: Unusual sys time: cpu0 +alarm Wed Aug 7 14:55:02 2012: Unusual sys time: cpu0 +alarm Wed Aug 7 14:55:06 2012: Unusual sys time: cpu0 </literallayout> +</example> +</section> +<section id="LE87294-PARENT"> + +<title><command>pmie</command> Intrinsic Operators</title> +<para><indexterm id="ITch06-17"><primary>pmie tool</primary><secondary>intrinsic +operators</secondary></indexterm><indexterm id="IG31371888213"><primary>intrinsic operators</primary> +</indexterm>The following sections describe some other useful intrinsic operators +for <command>pmie</command>. These operators are divided into three groups: +</para> +<itemizedlist> +<listitem><para>Arithmetic aggregation</para> +</listitem> +<listitem><para>The <literal>rate</literal> operator</para> +</listitem> +<listitem><para>Transitional operators</para> +</listitem></itemizedlist> +<section id="id5203384"> + +<title>Arithmetic Aggregation</title> +<para><indexterm id="IG31371888214"><primary>pmie tool</primary><secondary>arithmetic aggregation +</secondary></indexterm><indexterm id="IG31371888215"><primary>arithmetic aggregation</primary> +</indexterm>For set-valued arithmetic expressions, the following operators +reduce the dimensionality of the result by arithmetic aggregation along one +of the <replaceable>host</replaceable>, <replaceable>instance</replaceable>, +or <replaceable>sample time</replaceable> dimensions. For example, to aggregate +in the <replaceable>host</replaceable> dimension, the following operators +are provided:</para> +<variablelist> +<varlistentry> +<term><literal>avg_host</literal></term> +<listitem><para><indexterm id="IG31371888216"><primary>avg_host operator</primary></indexterm>Computes +the average value across all <replaceable>instances</replaceable> for the +same <replaceable>host</replaceable> and <replaceable>sample time</replaceable></para> +</listitem></varlistentry> +<varlistentry> +<term><literal>sum_host</literal></term> +<listitem><para><indexterm id="IG31371888217"><primary>sum_host operator</primary></indexterm>Computes +the total value across all <replaceable>instances</replaceable> for the same +<replaceable>host</replaceable> and <replaceable>sample time</replaceable></para> +</listitem></varlistentry> +<varlistentry> +<term><literal>count_host</literal></term> +<listitem><para><indexterm id="IG31371888218"><primary>count_host operator</primary></indexterm>Computes +the number of values across all <replaceable>instances</replaceable> for the +same <replaceable>host</replaceable> and <replaceable>sample time</replaceable></para> +</listitem></varlistentry> +<varlistentry> +<term><literal>min_host</literal></term> +<listitem><para><indexterm id="IG31371888219"><primary>min_host operator</primary></indexterm>Computes +the minimum value across all <replaceable>instances</replaceable> for the +same <replaceable>host</replaceable> and <replaceable>sample time</replaceable></para> +</listitem></varlistentry> +<varlistentry> +<term><literal>max_host</literal></term> +<listitem><para><indexterm id="IG31371888220"><primary>max_host operator</primary></indexterm>Computes +the maximum value across all <replaceable>instances</replaceable> for the +same <replaceable>host</replaceable> and <replaceable>sample time</replaceable></para> +</listitem></varlistentry> +</variablelist> +<para><indexterm id="IG31371888221"><primary>*_inst operator</primary></indexterm><indexterm id="IG31371888222"> +<primary>*_sample operator</primary></indexterm>Ten additional operators correspond +to the forms <literal>*_inst</literal> and <literal>*_sample</literal>.</para> +<para>The following example illustrates the use of an aggregate operator in +combination with an existential operator to answer the question “Does +some host currently have two or more busy processors?”</para> +<literallayout class="monospaced">// note '' to escape - in host name +poke = ":moomba :'mac-larry' :bitbucket"; +some_host ( + count_inst ( kernel.percpu.cpu.user $poke + + kernel.percpu.cpu.sys $poke > 0.7 ) >= 2 + ) + -> alarm "2 or more busy CPUs"; </literallayout> +</section> +<section id="id5203682"> + +<title>The <command>rate</command> Operator</title> +<para><indexterm id="IG31371888223"><primary>pmie tool</primary><secondary>rate operator</secondary> +</indexterm><indexterm id="IG31371888224"><primary>rate operator</primary></indexterm>The <literal>rate</literal> operator computes the rate of change of an arithmetic expression +as shown in the following example:</para> +<literallayout class="monospaced">rate mem.util.cached </literallayout> +<para>It returns the rate of change for the <literal>mem.util.cached</literal> +performance metric; that is, the rate at which page cache memory is being +allocated and released.</para> +<para>The <literal>rate</literal> intrinsic operator is most useful for metrics +with instantaneous value semantics. For metrics with counter semantics, <command> +pmie</command> already performs an implicit rate calculation (see the <xref linkend="LE59099-PARENT"/>) and the <literal>rate</literal> operator would +produce the second derivative with respect to time, which is less likely to +be useful.</para> +</section> +<section id="id5203810"> + +<title>Transitional Operators</title> +<para><indexterm id="IG31371888225"><primary>pmie tool</primary><secondary>transitional operators +</secondary></indexterm><indexterm id="IG31371888226"><primary>transitional operators</primary> +</indexterm>In some cases, an action needs to be triggered when an expression +changes from true to false or vice versa. The following operators take a logical +expression as an operand, and return a logical expression:</para> +<variablelist> +<varlistentry> +<term><literal>rising</literal></term> +<listitem><para>Has the value <literal>true</literal> when the operand transitions +from <literal>false</literal> to <literal>true</literal> in consecutive samples. +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>falling</literal></term> +<listitem><para>Has the value <literal>false</literal> when the operand transitions +from <literal>true</literal> to <literal>false</literal> in consecutive samples. +</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +</section> +<section id="LE60280-PARENT"> + +<title><command>pmie</command> Examples</title> +<para><indexterm id="ITch06-18"><primary>pmie tool</primary><secondary>real +examples</secondary></indexterm>The examples presented in this section are +task-oriented and use the full power of the <command>pmie</command> specification +language as described in <xref linkend="LE90227-PARENT"/>.</para> +<para><indexterm id="IG31371888228"><primary>${PCP_DEMOS_DIR}</primary></indexterm>Source code for the <command>pmie</command> +examples in this chapter, and many more examples, is provided within the +<citetitle>PCP Tutorials and Case Studies</citetitle>. <xref linkend="Z928441343sdc"/> and <xref linkend="Z928441176sdc"/> +illustrate monitoring CPU utilization and disk activity.</para> +<example id="Z928441343sdc"> +<title>Monitoring CPU Utilization</title> +<literallayout class="monospaced">// Some Common Performance Monitoring Scenarios +// +// The CPU Group +// +delta = 2 sec; // more often for demonstration purposes +// common prefixes +// +percpu = "kernel.percpu"; +all = "kernel.all"; +// Unusual usr-sys split when some CPU is more than 20% in usr mode +// and sys mode is at least 1.5 times usr mode +// +cpu_usr_sys = + some_inst ( + $percpu.cpu.sys > $percpu.cpu.user * 1.5 && + $percpu.cpu.user > 0.2 + ) + -> alarm "Unusual sys time: " "%i "; +// Over all CPUs, syscall_rate > 1000 * no_of_cpus +// +cpu_syscall = + $all.syscall > 1000 count/sec * hinv.ncpu + -> print "high aggregate syscalls: %v"; +// Sustained high syscall rate on a single CPU +// +delta = 30 sec; +percpu_syscall = + some_inst ( + $percpu.syscall > 2000 count/sec + ) + -> syslog "Sustained syscalls per second? " "[%i] %v "; +// the 1 minute load average exceeds 5 * number of CPUs on any host +hosts = ":gonzo :moomba"; // change as required +delta = 1 minute; // no need to evaluate more often than this +high_load = + some_host ( + $all.load $hosts #'1 minute' > 5 * hinv.ncpu + ) + -> alarm "High Load Average? " "%h: %v ";</literallayout> +</example> +<example id="Z928441176sdc"> +<title>Monitoring Disk Activity +</title> +<literallayout class="monospaced">// Some Common Performance Monitoring Scenarios +// +// The Disk Group +// +delta = 15 sec; // often enough for disks? +// common prefixes +// +disk = "disk"; +// Any disk performing more than 40 I/Os per second, sustained over +// at least 30 seconds is probably busy +// +delta = 30 seconds; +disk_busy = + some_inst ( + $disk.dev.total > 40 count/sec + ) +] -> shell "Mail -s 'Heavy systained disk traffic' sysadm"; +// Try and catch bursts of activity ... more than 60 I/Os per second +// for at least 25% of 8 consecutive 3 second samples +// +delta = 3 sec; +disk_burst = + some_inst ( + 25%_sample ( + $disk.dev.total @0..7 > 60 count/sec + ) + ) + -> alarm "Disk Burst? " "%i "; +// any SCSI disk controller performing more than 3 Mbytes per +// second is busy +// Note: the obscure 512 is to convert blocks/sec to byte/sec, +// and pmie handles the rest of the scale conversion +// +some_inst $disk.ctl.blktotal * 512 > 3 Mbyte/sec + -> alarm "Busy Disk Controller: " "%i ";</literallayout> +</example> +</section> +<section id="LE31514-PARENT"> + +<title>Developing and Debugging <command>pmie</command> +Rules</title> +<para> <indexterm id="ITch06-20"><primary>pmie tool</primary><secondary>developing +rules</secondary></indexterm>Given the <literal>-d</literal> command line +option, <command>pmie</command> executes in interactive mode, and the user +is presented with a menu of options:</para> +<literallayout class="monospaced">pmie debugger commands + f [file-name] - load expressions from given file or stdin + l [expr-name] - list named expression or all expressions + r [interval] - run for given or default interval + S time-spec - set start time for run + T time-spec - set default interval for run command + v [expr-name] - print subexpression for %h, %i and %v bindings + h or ? - print this menu of commands + q - quit +pmie> </literallayout> +<para>If both the <literal>-d</literal> option and a filename are present, +the expressions in the given file are loaded before entering interactive mode. +Interactive mode is useful for debugging new rules.</para> +</section> +<section id="LE91221-PARENT"> + +<title>Caveats and Notes on <command>pmie</command></title> +<para><indexterm id="IG31371888229"><primary>caveats</primary></indexterm>The following sections +provide important information for users of <command>pmie</command>.</para> +<section id="id5204255"> + +<title>Performance Metrics Wraparound</title> +<para><indexterm id="ITch06-21"><primary>performance metric wraparound</primary> +</indexterm><indexterm id="IG31371888230"><primary>PCP_COUNTER_WRAP variable</primary></indexterm><indexterm id="IG31371888231"> +<primary>metric wraparound</primary></indexterm>Performance metrics that are +cumulative counters may occasionally overflow their range and wraparound to +0. When this happens, an unknown value (printed as <literal>?</literal>) is +returned as the value of the metric for one sample (recall that the value +returned is normally a rate). You can have PCP interpolate a value based on +expected rate of change by setting the <literal>PCP_COUNTER_WRAP</literal> +environment variable.</para> +</section> +<section id="id5204304"> + +<title><command>pmie</command> Sample Intervals</title> +<para><indexterm id="ITch06-22"><primary>pmie tool</primary><secondary>sample +intervals</secondary></indexterm><indexterm id="IG31371888232"><primary>sample intervals</primary> +</indexterm>The sample interval (<literal>delta</literal>) should always be +long enough, particularly in the case of rates, to ensure that a meaningful +value is computed. Interval may vary according to the metric and your needs. +A reasonable minimum is in the range of ten seconds or several minutes. Although +PCP supports sampling rates up to hundreds of times per second, using +small sample intervals creates unnecessary load on the monitored system.</para> +</section> +<section id="id5204396"> + +<title><command>pmie</command> Instance Names</title> +<para><indexterm id="ITch06-23"><primary>pmie tool</primary><secondary>instance +names</secondary></indexterm>When you specify a metric instance name (<literal>#</literal><replaceable>identifier</replaceable>) in a <command>pmie</command> +expression, it is compared against the instance name looked up from either +a live collector system or an archive as follows:</para> +<itemizedlist> +<listitem><para>If the given instance name and the looked up name are the same, +they are considered to match.</para> +</listitem> +<listitem><para>Otherwise, the first two space separated tokens are extracted +from the looked up name. If the given instance name is the same as either of these +tokens, they are considered a match.</para> +</listitem></itemizedlist> +<para>For some metrics, notably the per process (<literal>proc.xxx.xxx</literal>) +metrics, the first token in the looked up instance name is impossible to determine +at the time you are writing <command>pmie</command> expressions. The above +policy circumvents this problem.</para> +</section> +<section id="id5204468"> + +<title><command>pmie</command> Error Detection</title> +<para><indexterm id="ITch06-24"><primary>pmie tool</primary><secondary>error +detection</secondary></indexterm><indexterm id="IG31371888233"><primary>error detection</primary> +</indexterm>The parser used in <command>pmie</command> is not particularly robust +in handling syntax errors. It is suggested that you check any problematic +expressions individually in interactive mode:</para> +<literallayout class="monospaced"><userinput>pmie -v -d</userinput> +pmie> f +<replaceable>expression</replaceable> +<userinput>Ctrl+D</userinput></literallayout> +<para>If the expression was parsed, its internal representation is shown: +</para> +<literallayout class="monospaced">pmie> <userinput>l</userinput></literallayout> +<para>The expression is evaluated twice and its value printed:</para> +<literallayout class="monospaced">pmie> <userinput>r 10sec</userinput></literallayout> +<para>Then quit:</para> +<literallayout class="monospaced">pmie> <userinput>q</userinput></literallayout> +<para>It is not always possible to detect semantic errors at parse time. This +happens when a performance metric descriptor is not available from the named +host at this time. A warning is issued, and the expression is put on a wait +list. The wait list is checked periodically (about every five minutes) to +see if the metric descriptor has become available. If an error is detected +at this time, a message is printed to the standard error stream +(<command>stderr</command>) and the offending expression is set aside.</para> +</section> +</section> +<section id="Z927039566sdc"> + +<title>Creating <command>pmie</command> Rules with <command>pmieconf</command></title> +<para><indexterm id="IG31371888234"><primary>pmie tool</primary><secondary>pmieconf rules</secondary> +</indexterm><indexterm id="IG31371888235"><primary>pmieconf tool</primary><secondary>rules</secondary> +</indexterm>The <command>pmieconf</command> tool is a command line utility +that is designed to aid the specification of <command>pmie</command> rules +from parameterized versions of the rules. <command>pmieconf</command> is used +to display and modify variables or parameters controlling the details of the +generated <command>pmie</command> rules.</para> +<para><command>pmieconf</command> reads two different forms of supplied input +files and produces a localized <command>pmie</command> configuration file +as its output.</para> +<para>The first input form is a generalized <command>pmie</command> rule file +such as those found below <filename>${PCP_VAR_DIR}/config/pmieconf</filename>. +These files contain the generalized rules which <command>pmieconf</command> +is able to manipulate. Each of the rules can be enabled or disabled, or the +individual variables associated with each rule can be edited.</para> +<para>The second form is an actual <command>pmie</command> configuration file +(that is, a file which can be interpreted by <command>pmie</command>, conforming +to the <command>pmie</command> syntax described in <xref linkend="LE90227-PARENT"/>). +This file is both input to and output from <command>pmieconf</command>.</para> +<para>The input version of the file contains any changed variables or rule +states from previous invocations of <command>pmieconf</command>, and the output +version contains both the changes in state (for any subsequent <command>pmieconf +</command> sessions) and the generated <command>pmie</command> syntax. The +<command>pmieconf</command> state is embedded within a <command>pmie</command> comment +block at the head of the output file and is not interpreted by <command>pmie</command> +itself.</para> +<para><indexterm id="IG31371888236"><primary>pmie tool</primary><secondary>procedures</secondary> +</indexterm><command>pmieconf</command> is an integral part of the <command>pmie</command> +daemon management process described in <xref linkend="Z927039824sdc"/>. <xref linkend="Z930357839sdc"/> and <xref linkend="Z930357878sdc"/> introduce the <command>pmieconf</command> tool through a series of typical operations.</para> +<procedure id="Z930357839sdc"> +<title>Display <command>pmieconf</command> Rules</title> +<step><para>Start <command>pmieconf</command> interactively (as the superuser).<literallayout class="monospaced"><userinput>pmieconf -f ${PCP_SYSCONF_DIR}/pmie/config.demo</userinput> +Updates will be made to ${PCP_SYSCONF_DIR}/pmie/config.demo + +pmieconf></literallayout></para> +</step><step><para>List the set of available <command>pmieconf</command> +rules by using the <command>rules</command> command.</para> +</step><step><para>List the set of rule groups using the <command>groups</command> command.</para> +</step><step><para>List only the enabled rules, using the <command>rules enabled</command> command.</para> +</step><step><para>List a single rule:</para> +<literallayout class="monospaced">pmieconf> <userinput>list memory.swap_low</userinput> + rule: memory.swap_low [Low free swap space] + help: There is only threshold percent swap space remaining - the system + may soon run out of virtual memory. Reduce the number and size of + the running programs or add more swap(1) space before it +completely + runs out. + predicate = + some_host ( + ( 100 * ( swap.free $hosts$ / swap.length $hosts$ ) ) + < $threshold$ + && swap.length $hosts$ > 0 // ensure swap in use + ) + vars: enabled = no + threshold = 10% + +pmieconf></literallayout> +</step><step><para>List one rule variable:<literallayout class="monospaced">pmieconf> <userinput>list memory.swap_low threshold</userinput> + rule: memory.swap_low [Low free swap space] + threshold = 10% + +pmieconf></literallayout></para> +</step> +</procedure> +<procedure id="Z930357878sdc"> +<title>Modify <command>pmieconf</command> Rules and Generate a <command>pmie</command> File</title> +<step><para>Lower the threshold for the <literal>memory.swap_low</literal> rule, and also change the <command>pmie</command> sample interval +affecting just this rule. The <literal>delta</literal> variable is special +in that it is not associated with any particular rule; it has been defined +as a global <command>pmieconf</command> variable. Global variables can be +displayed using the <command>list global</command> command to <command>pmieconf</command>, +and can be modified either globally or local to a specific rule. +<literallayout class="monospaced">pmieconf> <userinput>modify memory.swap_low threshold 5</userinput> + +pmieconf> <userinput>modify memory.swap_low delta "1 sec"</userinput> + +pmieconf></literallayout></para> +</step><step><para>Disable all of the rules except for the <literal>memory.swap_low</literal> rule so that you can see the effects of your change +in isolation.</para> +<para>This produces a relatively simple <command>pmie</command> configuration +file:<literallayout class="monospaced">pmieconf> <userinput>disable all</userinput> + +pmieconf> <userinput>enable memory.swap_low</userinput> + +pmieconf> <userinput>status</userinput> + verbose: off + enabled rules: 1 of 35 + pmie configuration file: ${PCP_SYSCONF_DIR}/pmie/config.demo + pmie processes (PIDs) using this file: (none found) + +pmieconf> quit</literallayout></para> +<para>You can also use the <command>status</command> command to verify that +only one rule is enabled at the end of this step.</para> +<para/> +</step><step id="Z930357553sdc"><para>Run <command>pmie</command> +with the new configuration file. Use a text editor to view the newly generated +<command>pmie</command> configuration file (<filename>${PCP_SYSCONF_DIR}/pmie/config.demo</filename>), and +then run the command:<literallayout class="monospaced"><userinput>pmie -T "1.5 sec" -v -l ${HOME}/demo.log ${PCP_SYSCONF_DIR}/pmie/config.demo</userinput> +memory.swap_low: false + +memory.swap_low: false + +<userinput>cat ${HOME}/demo.log</userinput> +Log for pmie on <replaceable>venus</replaceable> started Mon Jun 21 16:26:06 2012 + +pmie: PID = 21847, default host = <replaceable>venus</replaceable> + +[Mon Jun 21 16:26:07] pmie(21847) Info: evaluator exiting + +Log finished Mon Jun 21 16:26:07 2012</literallayout></para> +</step><step><para>Notice that both of the <command>pmieconf</command> +files used in the previous step are simple text files, as described in the <command>pmieconf(5)</command> man page:</para> +<literallayout class="monospaced"><userinput>file ${PCP_SYSCONF_DIR}/pmie/config.demo</userinput> +${PCP_SYSCONF_DIR}/pmie/config.demo: PCP pmie config (V.1) +<userinput>file ${PCP_VAR_DIR}/config/pmieconf/memory/swap_low</userinput> +${PCP_VAR_DIR}/config/pmieconf/memory/swap_low: PCP pmieconf rules (V.1)</literallayout> +</step> +</procedure> +</section> +<section id="Z927039824sdc"> + +<title>Management of <command>pmie</command> Processes</title> +<para><indexterm id="IG31371888237"><primary>pmie tool</primary><secondary>procedures</secondary> +</indexterm>The <command>pmie</command> process can be run as a daemon as +part of the system startup sequence, and can thus be used to perform automated, +live performance monitoring of a running system. To do this, run these commands +(as superuser):</para> +<literallayout class="monospaced"><userinput>chkconfig pmie on</userinput> +<userinput>${PCP_RC_DIR}/pmie start</userinput></literallayout> +<para>By default, these enable a single <command>pmie</command> process monitoring +the local host, with the default set of <command>pmieconf</command> rules +enabled (for more information about <command>pmieconf</command>, see <xref linkend="Z927039566sdc"/>). +<xref linkend="Z930363467sdc"/> illustrates how +you can use these commands to start any number of <command>pmie</command> +processes to monitor local or remote machines.</para> +<procedure id="Z930363467sdc"> +<title>Add a New <command>pmie</command> Instance to the <command>pmie</command> Daemon Management Framework</title> +<step><para>Use a text editor (as superuser) to edit the <command>pmie</command> +control file <filename>${PCP_PMIECONTROL_PATH}</filename>. +Notice the default entry toward the end of the file, which looks like this: +</para> +<literallayout class="monospaced">#Host S? Log File Arguments +LOCALHOSTNAME n PCP_LOG_DIR/pmie/LOCALHOSTNAME/pmie.log -c config.default</literallayout> +<para>This entry is used to enable a local <command>pmie</command> process. +Add a new entry for a remote host on your local network (for example, <literal>venus</literal>), by using your <command>pmie</command> configuration file +(see <xref linkend="Z927039566sdc"/>):</para> +<literallayout class="monospaced"> +#Host S? Log File Arguments +venus n PCP_LOG_DIR/pmie/venus/pmie.log -c config.demo +</literallayout> +<note><para>Without an absolute path, the configuration file (<literal>-c</literal> above) +will be resolved using <filename>${PCP_SYSCONF_DIR}/pmie</filename> - if <filename>config.demo</filename> +was created in <xref linkend="Z930357878sdc"/> it would be used here for host <literal>venus</literal>, +otherwise a new configuration file will be generated using the default rules +(at <filename>${PCP_SYSCONF_DIR}/pmie/config.demo</filename>).</para> +</note> +</step><step><para>Enable <command>pmie</command> daemon management: <literallayout class="monospaced"><userinput>chkconfig pmie on</userinput></literallayout></para> +<para>This simple step allows <command>pmie</command> to be started as part +of your machine's boot process.</para> +</step><step><para>Start the two <command>pmie</command> daemons. +At the end of this step, you should see two new <command>pmie</command> processes +monitoring the local and remote hosts:</para> +<literallayout class="monospaced">${PCP_RC_DIR}/pmie start +Performance Co-Pilot starting inference engine(s) ... +</literallayout> +<para>Wait a few moments while the startup scripts run. The <command>pmie</command> +start script uses the <command>pmie_check</command> script to do most of its work.</para> +<para>Verify that the <command>pmie</command> processes have started:</para> +<literallayout class="monospaced"><userinput>pcp</userinput> +Performance Co-Pilot configuration on pluto: + + platform: Linux pluto 3.10.0-0.rc7.64.el7.x86_64 #1 SMP + hardware: 8 cpus, 2 disks, 23960MB RAM + timezone: EST-10 + pmcd: Version 3.8.3-1, 8 agents + pmda: pmcd proc xfs linux mmv infiniband gluster elasticsearch<replaceable> + pmie: pluto: ${PCP_LOG_DIR}/pmie/pluto/pmie.log + venus: ${PCP_LOG_DIR}/pmie/venus/pmie.log</replaceable></literallayout> +</step> +</procedure> +<para>If a remote host is not up at the time when <command>pmie</command> +is started, the <command>pmie</command> process may exit. <command>pmie</command> +processes may also exit if the local machine is starved of memory resources. +To counter these adverse cases, it can be useful to have a <command>crontab</command> +entry running. Adding an entry as shown in <xref linkend="id5208584"/> +ensures that if one of the configured <command>pmie</command> processes exits, +it is automatically restarted.</para> +<note><para>Depending on your platform, the <command>crontab</command> entry discussed +here may already have been installed for you, as part of the package installation process. +In this case, the file <filename>/etc/cron.d/pcp-pmie</filename> will exist, and the rest +of this section can be skipped.</para> +</note> + +<section id="id5208584"> +<title>Add a <command>pmie</command> <command>crontab</command> Entry</title> +<para>To activate the maintenance and housekeeping scripts for a collection +of inference engines, execute the following tasks while logged into the local host +as the superuser (<literal>root</literal>):</para> +<orderedlist><listitem><para>Augment the <filename>crontab</filename> file +for the <literal>pcp</literal> user. For example:</para> +<literallayout class="monospaced"><userinput>crontab -l -u pcp > ${HOME}/crontab.txt</userinput></literallayout> +</listitem><listitem><para>Edit <filename>${HOME}/crontab.txt</filename>, adding lines +similar to those from the sample <filename>${PCP_VAR_DIR}/config/pmie/crontab</filename> +file for <literal>pmie_daily</literal> and <literal>pmie_check</literal>; +for example:</para> +<literallayout class="monospaced"># daily processing of pmie logs +10 0 * * * ${PCP_BINADM_DIR}/pmie_daily +# every 30 minutes, check pmie instances are running +25,55 * * * * ${PCP_BINADM_DIR}/pmie_check</literallayout> +</listitem><listitem><para>Make these changes permanent with this command: +</para> +<literallayout class="monospaced"><userinput>crontab -u pcp < ${HOME}/crontab.txt</userinput></literallayout> +</listitem></orderedlist> +</section> +<section id="id5205585"> + +<title>Global Files and Directories</title> +<para><indexterm id="IG31371888238"><primary>pmie tool</primary><secondary>global files and directories +</secondary></indexterm>The following global files and directories influence +the behavior of <command>pmie</command> and the <command>pmie</command> management +scripts:</para> +<variablelist condition="sgi_termlength:nextline" id="Z930361086sdc"> +<varlistentry> +<term><filename>${PCP_DEMOS_DIR}/pmie/*</filename></term> +<listitem><para>Contains sample <command>pmie</command> rules that may be +used as a basis for developing local rules.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_SYSCONF_DIR}/pmie/config.default</filename></term> +<listitem><para>Is the default <command>pmie</command> configuration file +that is used when the <command>pmie</command> daemon facility is enabled. +Generated by <command>pmieconf</command> if not manually setup beforehand. +</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_VAR_DIR}/config/pmieconf/*/*</filename></term> +<listitem><para>Contains the <command>pmieconf</command> rule definitions +(templates) in its subdirectories.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_PMIECONTROL_PATH}</filename></term> +<listitem><para>Defines which PCP collector hosts require a daemon <command>pmie</command> +to be launched on the local host, where the configuration file +comes from, where the <command>pmie</command> log file should be created, +and <command>pmie</command> startup options.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_VAR_DIR}/config/pmlogger/crontab</filename></term> +<listitem><para>Contains default <command>crontab</command> entries that +may be merged with the <command>crontab</command> entries for root to schedule +the periodic execution of the <command>pmie_check</command> script, for verifying +that <command>pmie</command> instances are running. +Only for platforms where a default <command>crontab</command> is not automatically +installed during the initial PCP package installation.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_LOG_DIR}/pmie/*</filename></term> +<listitem><para>Contains the <command>pmie</command> log files for the host. +These files are created by the default behavior of the <filename>${PCP_RC_DIR}/pmie</filename> +startup scripts.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5205812"> + +<title><command>pmie</command> Instances and Their Progress</title> +<para>The PMCD PMDA exports information about executing <command>pmie</command> +instances and their progress in terms of rule evaluations and action execution +rates.</para> +<variablelist condition="sgi_termlength:wide" id="Z929060000sdc"> +<varlistentry> +<term><command>pmie_check</command></term> +<listitem><para>This command is similar to the <command>pmlogger</command> +support script, <command>pmlogger_check</command>.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_RC_DIR}/pmie</filename></term> +<listitem><para>This start script supports the starting and stopping of multiple +<command>pmie</command> instances that are monitoring one or more hosts.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_TMP_DIR}/pmie</filename></term> +<listitem><para>The statistics that <command>pmie</command> gathers are maintained +in binary data structure files. These files are located in this directory.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmcd.pmie</literal> metrics</term> +<listitem><para>If <command>pmie</command> is running on a system with a PCP +collector deployment, the PMCD PMDA exports these metrics via the +<filename>pmcd.pmie</filename> group of metrics.</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +</chapter> + + +<chapter id="LE93354-PARENT"> + +<title>Archive Logging</title> +<para><indexterm id="IG31371888239"><primary>archive logs</primary><secondary>usage</secondary> +</indexterm>Performance monitoring and management in complex systems demands +the ability to accurately capture performance characteristics for subsequent +review, analysis, and comparison. Performance Co-Pilot (PCP) provides extensive +support for the creation and management of archive logs that capture a user-specified +profile of performance information to support retrospective performance analysis. +</para> +<para>The following major sections are included in this chapter:</para> +<itemizedlist> +<listitem><para><xref linkend="LE43411-PARENT"/>, presents the concepts and +issues involved with creating and using archive logs.</para> +</listitem> +<listitem><para><xref linkend="LE46764-PARENT"/>, describes the interaction +of the PCP tools with archive logs.</para> +</listitem> +<listitem><para><xref linkend="LE57424-PARENT"/>, shows some shortcuts for +setting up useful PCP archive logs.</para> +</listitem> +<listitem><para><xref linkend="Z930642977sdc"/>, provides information about +other archive logging features and sevices.</para> +</listitem> +<listitem><para><xref linkend="LE80113-PARENT"/>, presents helpful directions +if your archive logging implementation is not functioning correctly.</para> +</listitem></itemizedlist> +<section id="LE43411-PARENT"> + +<title>Introduction to Archive Logging</title> +<para><indexterm id="ITch07-2"><primary>pmlogger tool</primary><secondary> +archive logs</secondary></indexterm>Within the PCP, the <command>pmlogger</command> +utility may be configured to collect archives of performance metrics. +The archive creation process is simple and very flexible, incorporating the +following features:</para> +<itemizedlist> +<listitem><para>Archive log creation at either a PCP collector (typically +a server) or a PCP monitor system (typically a workstation), or at some designated +PCP archive logger host.</para> +</listitem> +<listitem><para>Concurrent independent logging, both local and remote. The +performance analyst can activate a private <command>pmlogger</command> instance +to collect only the metrics of interest for the problem at hand, independent +of other logging on the workstation or remote host.</para> +</listitem> +<listitem><para>Independent determination of logging frequency for individual +metrics or metric instances. For example, you could log the “5 minute” +load average every half hour, the write I/O rate on the DBMS log spindle every +10 seconds, and aggregate I/O rates on the other disks every minute.</para> +</listitem> +<listitem><para><indexterm id="IG31371888240"><primary>pmlc tool</primary><secondary>dynamic +adjustment</secondary></indexterm><indexterm id="IG31371888241"><primary>pmlogger tool</primary> +<secondary>pmlc control</secondary></indexterm>Dynamic adjustment of what +is to be logged, and how frequently, via <command>pmlc</command>. This feature +may be used to disable logging or to increase the sample interval during periods +of low activity or chronic high activity. +A local <command>pmlc</command> may interrogate and control a +remote <command>pmlogger</command>, subject to the access control restrictions +implemented by <command>pmlogger</command>.</para> +</listitem> +<listitem><para>Self-contained logs that include all system configuration +and metadata required to interpret the values in the log. These logs can be +kept for analysis at a much later time, potentially after the hardware or +software has been reconfigured and the logs have been stored as discrete, +autonomous files for remote analysis. The logs are endian-neutral and platform +independent - there is no requirement that the monitor host machine used for +analysis be similar to the collector machine in any way, nor do they have to +have the same versions of PCP. PCP archives created over 15 years ago can +still be replayed with the current versions of PCP!</para> +</listitem> +<listitem><para><indexterm id="IG31371888242"><primary>cron scripts</primary></indexterm><literal>cron</literal>-based +scripts to expedite the operational management, for example, +log rotation, consolidation, and culling. Another helper tool, +<command>pmlogconf</command> can be used to generate suitable +logging configurations for a variety of situations.</para> +</listitem> +<listitem><para><indexterm id="IG31371888243"><primary>mkaf tool</primary></indexterm><indexterm id="IG31371888244"> +<primary>pmafm tool</primary><secondary>archive folios</secondary></indexterm>Archive +folios as a convenient aggregation of multiple archive logs. Archive folios +may be created with the <command>mkaf</command> utility and processed with +the <command>pmafm</command> tool.</para> +</listitem></itemizedlist> +<section id="id5206288"> + +<title>Archive Logs and the PMAPI</title> +<para><indexterm id="IG31371888245"><primary>archive logs</primary><secondary>PMAPI</secondary> +</indexterm>Critical to the success of the PCP archive logging scheme is the +fact that the library routines providing access to real-time feeds of performance +metrics also provide access to the archive logs.</para> +<para><indexterm id="IG31371888246"><primary>PMAPI</primary><secondary>archive logs</secondary> +</indexterm>Live feeds (or real-time) sources of performance metrics and archives +are literally interchangeable, with a single Performance Metrics Application +Programming Interface (PMAPI) that preserves the same semantics for both styles +of metric source. In this way, applications and tools developed against the +PMAPI can automatically process either live or historical performance data. +</para> +</section> +<section id="id5206362"> + +<title>Retrospective Analysis Using Archive Logs</title> +<para><indexterm id="IG31371888247"><primary>archive logs</primary><secondary>retrospective analysis +</secondary></indexterm><indexterm id="IG31371888248"><primary>retrospective analysis</primary> +</indexterm>One of the most important applications of archive logging services +provided by PCP is in the area of retrospective analysis. In many cases, understanding +today's performance problems can be assisted by side-by-side comparisons with +yesterday's performance. With routine creation of performance archive logs, +you can concurrently replay pictures of system performance for two or more +periods in the past.</para> +<para>Archive logs are also an invaluable source of intelligence when trying +to diagnose what went wrong, as in a performance post-mortem. Because the PCP +archive logs are entirely self-contained, this analysis can be performed off-site +if necessary.</para> +<para>Each archive log contains metric values from only one host. However, +many PCP tools can simultaneously visualize values from multiple archives +collected from different hosts.</para> +<para>The archives can be replayed using the inference engine (<command>pmie</command> +is an application that uses the PMAPI). This allows you to +automate the regular, first-level analysis of system performance.</para> +<para>Such analysis can be performed by constructing suitable expressions +to capture the essence of common resource saturation problems, then periodically +creating an archive and playing it against the expressions. For example, you +may wish to create a daily performance audit (perhaps run by the <command>cron</command> +command) to detect performance regressions.</para> +<para>For more about <command>pmie</command>, see <xref linkend="LE21414-PARENT"/>. +</para> +</section> +<section id="id5206454"> + +<title>Using Archive Logs for Capacity Planning</title> +<para><indexterm id="IG31371888249"><primary>archive logs</primary><secondary>capacity planning +</secondary></indexterm><indexterm id="IG31371888250"><primary>capacity planning</primary></indexterm>By +collecting performance archives with relatively long sampling periods, or +by reducing the daily archives to produce summary logs, the capacity planner +can collect the base data required for forward projections, and can estimate +resource demands and explore “what if” scenarios by replaying +data using visualization tools and the inference engine.</para> +</section> +</section> +<section id="LE46764-PARENT"> + +<title>Using Archive Logs with Performance Tools</title> +<para><indexterm id="ITch07-4"><primary>performance visualization tools</primary> +</indexterm>Most PCP tools default to real-time display of current values +for performance metrics from PCP collector host(s). However, most PCP tools +also have the capability to display values for performance metrics retrieved +from PCP archive log(s). The following sections describe plans, steps, and +general issues involving archive logs and the PCP tools.</para> +<section id="id5206523"> + +<title>Coordination between <command>pmlogger</command> and PCP tools</title> +<para><indexterm id="IG31371888251"><primary>pmlogger tool</primary><secondary>PCP tool coordination +</secondary></indexterm>Most commonly, a PCP tool would be invoked with the <literal>-a</literal> option to process an archive log some time after <command>pmlogger</command> had finished creating the archive. However, a tool such as +<command>pmchart</command> that uses a Time Control dialog (see <xref linkend="LE76997-PARENT"/>) +stops when the end of archive is reached, but could resume if more data is +written to the PCP archive log.<note><para><indexterm id="IG31371888252"><primary>SIGUSR1 signal +</primary></indexterm><indexterm id="IG31371888253"><primary>flush command</primary></indexterm><indexterm id="IG31371888254"> +<primary>pmlc tool</primary><secondary>flush command</secondary></indexterm><command>pmlogger</command> +uses buffered I/O to write the archive log so that the +end of the archive may be aligned with an I/O buffer boundary, rather than +with a logical archive log record. If such an archive was read by a PCP tool, +it would appear truncated and might confuse the tool. These problems may be +avoided by sending <command>pmlogger</command> a <literal>SIGUSR1</literal> +signal, or by using the <command>flush</command> command of <command>pmlc</command> +to force <command>pmlogger</command> to flush its output buffers. +</para> +</note></para> +</section><section id="id5206675"> + +<title>Administering PCP Archive Logs Using <command>cron</command> Scripts +</title> +<para><indexterm id="ITch07-6"><primary>cron scripts</primary></indexterm><indexterm id="IG31371888255"> +<primary>scripts</primary></indexterm>Many operating systems support +the <literal>cron</literal> process scheduling system.</para> +<para><indexterm id="ITch07-7"><primary>pmlogger_check script</primary></indexterm><indexterm id="IG31371888256"> +<primary>pmlogger_daily script</primary></indexterm><indexterm id="IG31371888257"><primary>pmsnap +tool</primary><secondary>script usage</secondary></indexterm><indexterm id="IG31371888258"><primary> +pmlogger_merge script</primary></indexterm>PCP supplies shell scripts to use +the <literal>cron</literal> functionality to help manage your archive logs. +The following scripts are supplied:</para> +<variablelist> +<varlistentry> +<term><emphasis role="bold">Script</emphasis></term><listitem><para><emphasis role="bold">Description</emphasis></para></listitem></varlistentry> +<varlistentry> +<term><literal>pmlogger_daily(1)</literal></term> +<listitem><para>Performs a daily housecleaning of archive logs and notices. +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmlogger_merge(1)</literal></term> +<listitem><para><literal/>Merges archive logs and is called by <literal>pmlogger_daily</literal>.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmlogger_check(1)</literal></term> +<listitem><para>Checks to see that all desired <command>pmlogger</command> +processes are running on your system, and invokes any that are missing for +any reason.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmlogconf(1)</literal></term> +<listitem><para>Generates suitable <command>pmlogger</command> configuration +files based on a pre-defined set of templates. It can probe the state of the +system under observation to make informed decisions about which metrics to +record. This is an extensible facility, allowing software upgrades and new +PMDA installations to add to the existing set of templates.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmsnap(1)</command></term> +<listitem><para>Generates graphic image snapshots of <command>pmchart</command> +performance charts at regular intervals.</para> +</listitem></varlistentry> +</variablelist> +<para><indexterm id="IG31371888259"><primary>${PCP_PMLOGGERCONTROL_PATH} file</primary> +</indexterm>The configuration files used by these scripts can be edited to +suit your particular needs, and are generally controlled by the +<filename>${PCP_PMLOGGERCONTROL_PATH}</filename> file (<literal>pmsnap</literal> +has an additional control file, <filename>${PCP_PMSNAPCONTROL_PATH}</filename>). +Complete information on these scripts is available in the <command>pmlogger_daily(1)</command> +and <command>pmsnap(1)</command> man pages.</para> +</section> +<section id="LE92914-PARENT"> + +<title>Archive Log File Management</title> +<para><indexterm id="IG31371888260"><primary>archive logs</primary><secondary>file management +</secondary></indexterm>PCP archive log files can occupy a great deal of disk +space, and management of archive logs can be a large task in itself. The following +sections provide information to assist you in PCP archive log file management. +</para> +<section id="id5206941"> + +<title>Basename Conventions</title> +<para><indexterm id="IG31371888261"><primary>basename conventions</primary></indexterm>When a +PCP archive is created by <command>pmlogger</command>, an archive basename +must be specified and several physical files are created, as shown in <xref linkend="id5206972"/>.</para> +<table id="id5206972" frame="topbot"> + +<title>Filenames for PCP Archive Log Components (<literal>archive</literal>.<replaceable>*</replaceable>)</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="102*"/> +<colspec colwidth="294*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Filename</para></entry> +<entry align="left" valign="bottom"><para>Contents</para></entry></row></thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para><filename>archive.</filename><emphasis role="bold"/><replaceable>index</replaceable></para></entry> +<entry align="left" valign="top"><para>Temporal index for rapid access to +archive contents.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><filename>archive.</filename><replaceable>meta</replaceable></para></entry> +<entry align="left" valign="top"><para>Metadata descriptions for performance +metrics and instance domains appearing in the archive.</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><filename>archive.N</filename></para></entry> +<entry align="left" valign="top"><para>Volumes of performance metrics values, +for <filename>N</filename> = 0,1,2,...</para></entry></row></tbody></tgroup> +</table> +</section> +<section id="id5207181"> + +<title>Log Volumes</title> +<para><indexterm id="IG31371888262"><primary>log volumes</primary></indexterm>A single PCP archive +may be partitioned into a number of volumes. These volumes may expedite management +of the archive; however, the metadata file and at least one volume must be +present before a PCP tool can process the archive.</para> +<para>You can control the size of an archive log volume by using the <literal>-v</literal> command line option to <command>pmlogger</command>. This option +specifies how large a volume should become before <command>pmlogger</command> +starts a new volume. Archive log volumes retain the same base filename as +other files in the archive log, and are differentiated by a numeric suffix +that is incremented with each volume change. For example, you might have a +log volume sequence that looks like this:</para> +<literallayout class="monospaced">netserver-log.0 +netserver-log.1 +netserver-log.2</literallayout> +<para><indexterm id="IG31371888263"><primary>SIGHUP signal</primary></indexterm><indexterm id="IG31371888264"><primary> +pmlc tool</primary><secondary>SIGHUP signal</secondary></indexterm>You can +also cause an existing log to be closed and a new one to be opened by sending +a <literal>SIGHUP</literal> signal to <command>pmlogger</command>, or by using +the <command>pmlc</command> command to change the <command>pmlogger</command> +instructions dynamically, without interrupting <command>pmlogger</command> +operation. Complete information on log volumes is found in the <command>pmlogger(1)</command> +man page.</para> +</section><section id="id5207300"> + +<title>Basenames for Managed Archive Log Files</title> +<para>The PCP archive management tools support a consistent scheme for selecting +the basenames for the files in a collection of archives and for mapping these +files to a suitable directory hierarchy.</para> +<para>Once configured, the PCP tools that manage archive logs employ a consistent +scheme for selecting the basename for an archive each time <command>pmlogger</command> +is launched, namely the current date and time in the format YYYYMMDD.HH.MM. +Typically, at the end of each day, all archives for a particular host on that +day would be merged to produce a single archive with a basename constructed +from the date, namely YYYYMMDD. The <literal>pmlogger_daily</literal> script +performs this action and a number of other routine housekeeping chores.</para> +</section><section id="id5207335"> + +<title>Directory Organization for Archive Log Files</title> +<para>If you are using a deployment of PCP tools and daemons to collect metrics +from a variety of hosts and storing them all at a central location, you should +develop an organized strategy for storing and naming your log files.</para> +<note><para><indexterm id="IG31371888265"><primary>pmchart tool</primary><secondary>short-term +executions</secondary></indexterm>There are many possible configurations of <command>pmlogger</command>, +as described in <xref linkend="LE56598-PARENT"/>. The directory +organization described in this section is recommended for any system on which +<command>pmlogger</command> is configured for permanent execution (as opposed to short-term +executions, for example, as launched from <command>pmchart</command> to record +some performance data of current interest).</para> +</note> +<para>Typically, the filesystem structure can be used to reflect the +number of hosts for which a <command>pmlogger</command> instance is expected +to be running locally, obviating the need for lengthy and cumbersome filenames. +It makes considerable sense to place all logs for a particular host in a separate +directory named after that host. Because each instance of <command>pmlogger</command> +can only log metrics fetched from a single host, this also simplifies +some of the archive log management and administration tasks.</para> +<para>For example, consider the filesystem and naming structure shown in <xref linkend="id5207462"/>.</para> +<figure id="id5207462"><title>Archive Log Directory Structure</title><mediaobject><imageobject><imagedata fileref="figures/log-directory.svg"/></imageobject><textobject><phrase>Archive Log Directory Structure</phrase></textobject></mediaobject></figure> +<para><indexterm id="IG31371888266"><primary>${PCP_PMLOGGERCONTROL_PATH} file</primary> +</indexterm>The specification of where to place the archive log files for +particular <command>pmlogger</command> instances is encoded in the configuration +file <filename>${PCP_PMLOGGERCONTROL_PATH}</filename>, +and this file should be customized on each host running an instance of <command>pmlogger</command>.</para> +<para>If many archives are being created, and the associated PCP collector +systems form peer classes based upon service type (Web servers, +DBMS servers, NFS servers, and so on), then it may be appropriate to introduce +another layer into the directory structure, or use symbolic links to group +together hosts providing similar service types.</para> +</section> +<section id="id5207540"> + +<title>Configuration of <command>pmlogger</command></title> +<para><indexterm id="IG31371888267"><primary>pmlogger tool</primary><secondary>configuration +</secondary></indexterm>The configuration files used by <command>pmlogger</command> +describe which metrics are to be logged. Groups of metrics may +be logged at different intervals to other groups of metrics. Two states, mandatory +and advisory, also apply to each group of metrics, defining whether metrics +definitely should be logged or not logged, or whether a later advisory definition +may change that state.</para> +<para>The mandatory state takes precedence if it is <literal>on</literal> +or <literal>off</literal>, causing any subsequent request for a change in +advisory state to have no effect. If the mandatory state is <literal>maybe</literal>, +then the advisory state determines if logging is enabled or not. +</para> +<para>The mandatory states are <literal>on</literal>, <literal>off</literal>, +and <literal>maybe</literal>. The advisory states, which only affect metrics +that are mandatory <literal>maybe</literal>, are <literal>on</literal> and +<literal>off</literal>. Therefore, a metric that is mandatory <literal>maybe</literal> +in one definition and advisory <literal>on</literal> in another definition +would be logged at the advisory interval. Metrics that are not specified in +the <command>pmlogger</command> configuration file are mandatory <literal>maybe</literal> +and advisory <literal>off</literal> by default and are not logged.</para> +<para>A complete description of the <command>pmlogger</command> configuration +format can be found on the <command>pmlogger(1)</command> man page.</para> +</section> +<section id="id5207708"> + +<title>PCP Archive Contents</title> +<para><indexterm id="IG31371888268"><primary>archive logs</primary><secondary>contents</secondary> +</indexterm><indexterm id="IG31371888269"><primary>pmdumplog tool</primary><secondary>archive +log contents</secondary></indexterm>Once a PCP archive log has been created, +the <command>pmdumplog</command> utility may be used to display various information +about the contents of the archive. For example, start with the following command: +</para> +<para><literal>pmdumplog -l ${PCP_LOG_DIR}/pmlogger/www.sgi.com/19960731</literal></para> +<para>It might produce the following output:</para> +<literallayout class="monospaced">Log Label (Log Format Version 1) +Performance metrics from host www.sgi.com + commencing Wed Jul 31 00:16:34.941 1996 + ending Thu Aug 1 00:18:01.468 1996</literallayout> +<para>The simplest way to discover what performance metrics are contained +within an archive is to use <literal>pminfo</literal> as shown in <xref linkend="Z984165598sdc"/>: +</para> +<example id="Z984165598sdc"> +<title>Using <literal>pminfo</literal> to Obtain Archive Information</title> +<literallayout class="monospaced"><literal>pminfo -a ${PCP_LOG_DIR}/pmlogger/www.sgi.com/19960731 network.mbuf</literal> +network.mbuf.alloc +network.mbuf.typealloc +network.mbuf.clustalloc +network.mbuf.clustfree +network.mbuf.failed +network.mbuf.waited +network.mbuf.drained</literallayout> +</example> +</section> +</section> +</section> +<section id="LE57424-PARENT"> + +<title>Cookbook for Archive Logging</title> +<para><indexterm id="IG31371888270"><primary>cookbook</primary></indexterm><indexterm id="IG31371888271"><primary> +pmlogger tool</primary><secondary>cookbook tasks</secondary></indexterm>The +following sections present a checklist of tasks that may be performed to enable +PCP archive logging with minimal effort. For a complete explanation, refer +to the other sections in this chapter and the man pages for <command>pmlogger +</command> and related tools.</para> +<section id="id5207850"> + +<title>Primary Logger</title> +<para><indexterm id="IG31371888272"><primary>primary archive</primary></indexterm>Assume you +wish to activate primary archive logging on the PCP collector host <literal>pluto</literal>. +Execute the following while logged into <literal>pluto</literal> as the superuser +(<literal>root</literal>).</para> +<orderedlist> +<listitem><para>Start <command>pmcd</command> and <command>pmlogger</command>:</para> +<literallayout class="monospaced"><userinput>chkconfig pmcd on</userinput> +<userinput>chkconfig pmlogger on</userinput> +<userinput>${PCP_RC_DIR}/pmcd start</userinput> +Starting pmcd ... +<userinput>${PCP_RC_DIR}/pmlogger start</userinput> +Starting pmlogger ...</literallayout> +</listitem><listitem><para>Verify that the primary <command>pmlogger</command> +instance is running:</para> +<literallayout class="monospaced"><userinput>pcp</userinput> +Performance Co-Pilot configuration on pluto: + + platform: Linux pluto 3.10.0-0.rc7.64.el7.x86_64 #1 SMP + hardware: 8 cpus, 2 disks, 23960MB RAM + timezone: EST-10 + pmcd: Version 3.8.3-1, 8 agents + pmda: pmcd proc xfs linux mmv infiniband gluster elasticsearch<replaceable> + pmlogger: primary logger: pluto/20130815.10.00</replaceable> + pmie: pluto: ${PCP_LOG_DIR}/pmie/pluto/pmie.log + venus: ${PCP_LOG_DIR}/pmie/venus/pmie.log</literallayout> +</listitem><listitem><para>Verify that the archive files are being created +in the expected place:</para> +<literallayout class="monospaced"><userinput>ls ${PCP_LOG_DIR}/pmlogger/pluto</userinput> +20130815.10.00.0 +20130815.10.00.index +20130815.10.00.meta +Latest +pmlogger.log</literallayout> +</listitem><listitem><para>Verify that no errors are being logged, and the rate of +expected growth of the archives:</para> +<literallayout class="monospaced"><userinput>cat ${PCP_LOG_DIR}/pmlogger/pluto/pmlogger.log</userinput> +Log for pmlogger on pluto started Thu Aug 15 10:00:11 2013 + +Config parsed +Starting primary logger for host "pluto" +Archive basename: 20130815.00.10 + +Group [26 metrics] { + hinv.map.lvname + ... + hinv.ncpu +} logged once: 1912 bytes + +Group [11 metrics] { + kernel.all.cpu.user + ... + kernel.all.load +} logged every 60 sec: 372 bytes or 0.51 Mbytes/day + +...</literallayout> +</listitem> +</orderedlist> +</section> +<section id="id5208266"> + +<title>Other Logger Configurations</title> +<para>Assume you wish to create archive logs on the local host for performance +metrics collected from the remote host <literal>venus</literal>. Execute all +of the following tasks while logged into the local host as the superuser (<literal>root</literal>).</para> +<procedure id="id5208288"> +<title>Creating Archive Logs</title> +<step><para>Create a suitable <command>pmlogger</command> configuration +file. There are several options:</para> +<itemizedlist> +<listitem><para>Run the <command>pmlogconf(1)</command> utility to generate +a configuration file, and (optionally) interactively customize it further to +suit local needs. +</para> +<literallayout class="monospaced"><userinput>${PCP_BINADM_DIR}/pmlogconf ${PCP_SYSCONF_DIR}/pmlogger/config.venus</userinput> +Creating config file "${PCP_SYSCONF_DIR}/pmlogger/config.venus" using default settings + +<userinput>${PCP_BINADM_DIR}/pmlogconf ${PCP_SYSCONF_DIR}/pmlogger/config.venus</userinput> + +Group: utilization per CPU +Log this group? [n] y +Logging interval? [default] + +Group: utilization (usr, sys, idle, ...) over all CPUs +Log this group? [y] y +Logging interval? [default] + +Group: per spindle disk activity +Log this group? [n] y + +...</literallayout> +</listitem> +<listitem><para>Do nothing - a default configuration will be created in the +following step, using <command>pmlogconf(1)</command> probing and automatic file +generation based on the metrics available at the remote host. The +<filename>${PCP_RC_DIR}/pmlogger</filename> start script handles this.</para> +</listitem> +<listitem><para>Manually - create a configuration file with a text editor, +or arrange to have one put in place by configuration management tools like +<ulink url="https://puppetlabs.com/">Puppet</ulink> or +<ulink url="http://www.opscode.com/chef/">Chef</ulink>.</para> +</listitem> +</itemizedlist> +</step><step><para>Edit <filename>${PCP_PMLOGGERCONTROL_PATH}</filename>. +Using the line for <literal>remote</literal> as a template, add +the following line to the file:</para> +<literallayout class="monospaced"><userinput>venus n n PCP_LOG_DIR/pmlogger/venus -r -T24h10m -c config.venus</userinput></literallayout> +</step><step><para>Start <command>pmlogger</command>:</para> +<literallayout class="monospaced"><userinput>${PCP_BINADM_DIR}/pmlogger_check</userinput> +Restarting pmlogger for host "venus" ..... done</literallayout> +</step><step><para>Verify that the <command>pmlogger</command> instance +is running:</para> +<literallayout class="monospaced"><userinput>pcp</userinput> +Performance Co-Pilot configuration on pluto: + + platform: Linux pluto 3.10.0-0.rc7.64.el7.x86_64 #1 SMP + hardware: 8 cpus, 2 disks, 23960MB RAM + timezone: EST-10 + pmcd: Version 3.8.3-1, 8 agents + pmda: pmcd proc linux xfs mmv infiniband gluster elasticsearch<replaceable> + pmlogger: primary logger: pluto/20130815.10.00 + venus.redhat.com: venus/20130815.11.15</replaceable> +<userinput>pmlc</userinput> +pmlc> <userinput>show loggers</userinput> +The following pmloggers are running on pluto: + primary (19144) 5141 +pmlc> <userinput>connect 5141</userinput> +pmlc> <userinput>status</userinput><replaceable> +pmlogger [5141] on host pluto is logging metrics from host venus</replaceable> +log started Thu Aug 15 11:15:39 2013 (times in local time) +last log entry Thu Aug 15 11:47:39 2013 +current time Thu Aug 15 11:48:13 2013 +log volume 0 +log size 146160</literallayout> +</step> +</procedure> +<para>To create archive logs on the local host for performance metrics collected +from multiple remote hosts, repeat the steps in <xref linkend="id5208288"/> +for each remote host (each with a new <filename>control</filename> file entry).</para> +</section> +<section id="id5208588"> + +<title>Archive Log Administration</title> +<para><indexterm id="IG31371888290"><primary>archive logs</primary><secondary>administration +</secondary></indexterm>Assume the local host has been set up to create archive +logs of performance metrics collected from one or more hosts (which may be +either the local host or a remote host).</para> +<note><para>Depending on your platform, the <command>crontab</command> entry discussed +here may already have been installed for you, as part of the package installation process. +In this case, the file <filename>/etc/cron.d/pcp-pmlogger</filename> will exist, and the rest +of this section can be skipped.</para> +</note> +<para>To activate the maintenance and housekeeping scripts for a collection +of archive logs, execute the following tasks while logged into the local host +as the superuser (<literal>root</literal>):</para> +<orderedlist><listitem><para>Augment the <filename>crontab</filename> file +for the <literal>pcp</literal> user. For example:</para> +<literallayout class="monospaced"><userinput>crontab -l -u pcp > ${HOME}/crontab.txt</userinput></literallayout> +</listitem><listitem><para>Edit <filename>${HOME}/crontab.txt</filename>, adding lines +similar to those from the sample <filename>${PCP_VAR_DIR}/config/pmlogger/crontab</filename> +file for <literal>pmlogger_daily</literal> and <literal>pmlogger_check</literal>; +for example:</para> +<literallayout class="monospaced"># daily processing of archive logs +10 0 * * * ${PCP_BINADM_DIR}/pmlogger_daily +# every 30 minutes, check pmlogger instances are running +25,55 * * * * ${PCP_BINADM_DIR}/pmlogger_check</literallayout> +</listitem><listitem><para>Make these changes permanent with this command: +</para> +<literallayout class="monospaced"><userinput>crontab -u pcp < ${HOME}/crontab.txt</userinput></literallayout> +</listitem></orderedlist> +</section> +</section> +<section id="Z930642977sdc"> + +<title>Other Archive Logging Features and Services</title> +<para>Other archive logging features and services include PCP archive folios, +manipulating archive logs, primary logger, and using <command>pmlc</command>. +</para> +<section id="LE73509-PARENT"> + +<title>PCP Archive Folios</title> +<para><indexterm id="ITch07-9"><primary>folios</primary></indexterm><indexterm id="IG31371888291"> +<primary>archive logs</primary><secondary>folios</secondary></indexterm><indexterm id="IG31371888292"> +<primary>pmchart tool</primary><secondary>record mode</secondary></indexterm><indexterm id="IG31371888293"> +<primary>pmcollectl tool</primary><secondary>record mode</secondary></indexterm>A +collection of one or more PCP archive logs may be combined with a control +file to produce a PCP archive folio. Archive folios are created using either <literal>mkaf</literal> or the interactive record mode services of various PCP monitor tools (e.g. <command>pmchart</command> and <command>pmcollectl</command>).</para> +<para><indexterm id="IG31371888294"><primary>pmlogger tool</primary><secondary>folios</secondary> +</indexterm>The automated archive log management services also create an archive +folio named <filename>Latest</filename> for each managed <command>pmlogger +</command> instance, to provide a symbolic name to the most recent archive +log. With reference to <xref linkend="id5207462"/>, this would mean the +creation of the folios <filename>${PCP_LOG_DIR}/pmlogger/one/Latest</filename> +and <filename>${PCP_LOG_DIR}/pmlogger/two/Latest</filename>.</para> +<para><indexterm id="IG31371888295"><primary>pmafm tool</primary><secondary>interactive commands +</secondary></indexterm>The <command>pmafm</command> utility is completely +described in the <command>pmafm(1)</command> man page, and provides +the interactive commands (single commands may also be executed from the command +line) for the following services:</para> +<itemizedlist> +<listitem><para>Checking the integrity of the archives in the folio.</para> +</listitem> +<listitem><para>Displaying information about the component archives.</para> +</listitem> +<listitem><para>Executing PCP tools with their source of performance metrics +assigned concurrently to all of the component archives (where the tool supports +this), or serially executing the PCP tool once per component archive.</para> +</listitem> +<listitem><para>If the folio was created by a single PCP monitoring tool, +replaying all of the archives in the folio with that monitoring tool.</para> +</listitem> +<listitem><para>Restricting the processing to particular archives, or the +archives associated with particular hosts.</para> +</listitem></itemizedlist> +</section> +<section id="id5208950"> + +<title>Manipulating Archive Logs with <command>pmlogextract</command></title> +<para><indexterm id="ITch07-10"><primary>pmlogextract tool</primary></indexterm> +The <literal>pmlogextract</literal> tool takes a number of PCP archive logs +from a single host and performs the following tasks:</para> +<itemizedlist> +<listitem><para>Merges the archives into a single log, while maintaining the +correct time stamps for all values.</para> +</listitem> +<listitem><para>Extracts all metric values within a temporal window that could +encompass several archive logs.</para> +</listitem> +<listitem><para>Extracts only a configurable subset of metrics from the archive +logs.</para> +</listitem></itemizedlist> +<para>See the <command>pmlogextract(1)</command> man page for +full information on this command.</para> +</section> +<section id="id5208951"> + +<title>Summarizing Archive Logs with <command>pmlogsummary</command></title> +<para><indexterm id="ITch07-11"><primary>pmlogsummary tool</primary></indexterm> +The <literal>pmlogsummary</literal> tool provides statistical summaries of +archives, or specific metrics within archives, or specific time windows of +interest in an archive. These summaries include various averages, minima, +maxima, sample counts, histogram bins, and so on.</para> +<para>As an example, for Linux host <literal>pluto</literal>, report on its +use of anonymous huge pages - average use, maximum, time at which maximum +occured, total number of samples in the archive, and the units used for the +values - as shown in <xref linkend="Z984165598nat"/>: +</para> +<example id="Z984165598nat"> +<title>Using <literal>pmlogsummary</literal> to Summarize Archive Information</title> +<literallayout class="monospaced"><userinput>pmlogsummary -MIly ${PCP_LOG_DIR}/pmlogger/pluto/20130815 mem.util.anonhugepages</userinput> +Performance metrics from host pluto + commencing Thu Aug 15 00:10:12.318 2013 + ending Fri Aug 16 00:10:12.299 2013 + +mem.util.anonhugepages 7987742.326 8116224.000 15:02:12.300 1437 Kbyte + +<userinput>pminfo -t mem.util.anonhugepages</userinput> +mem.util.anonhugepages [amount of memory in anonymous huge pages]</literallayout> +</example> +<para>See the <command>pmlogsummary(1)</command> man page for +detailed information about this commands many options.</para> +</section> +<section id="id5209027"> + +<title>Primary Logger</title> +<para><indexterm id="ITch07-14"><primary>primary logger</primary></indexterm><indexterm id="ITch07-16"><primary>pmlogger tool</primary><secondary>primary instance +</secondary></indexterm>On each system for which PMCD is active (each PCP +collector system), there is an option to have a distinguished instance of +the archive logger <command>pmlogger</command> (the “primary” +logger) launched each time PMCD is started. This may be used to ensure the +creation of minimalist archive logs required for ongoing system management +and capacity planning in the event of failure of a system where a remote +<command>pmlogger</command> may be running, or because the preferred archive logger +deployment is to activate <command>pmlogger</command> on each PCP collector +system.</para> +<para>Run the following command as superuser on each PCP collector system +where you want to activate the primary <command>pmlogger</command>:</para> +<literallayout class="monospaced"><userinput>chkconfig pmlogger on</userinput></literallayout> +<para>The primary logger launches the next time the <command>${PCP_RC_DIR}/pmlogger start</command> script runs. +If you wish this to happen immediately, follow up with this command:</para> +<literallayout class="monospaced"><userinput>${PCP_BINADM_DIR}/pmlogger_check -V</userinput></literallayout> +<para><indexterm id="IG31371888296"><primary>${PCP_PMLOGGERCONTROL_PATH} file</primary></indexterm><indexterm id="IG31371888297"> +<primary>${PCP_SYSCONF_DIR}/pmlogger/config.default file</primary></indexterm>When +it is started in this fashion, the <filename>${PCP_PMLOGGERCONTROL_PATH}</filename> +must use the second field of one configuration line to designate the primary logger, +and usually will also use the <command>pmlogger</command> configuration file +<filename>${PCP_SYSCONF_DIR}/pmlogger/config.default</filename> (although the latter +is not mandatory).</para> +</section> +<section id="id5209191"> + +<title>Using <command>pmlc</command></title> +<para><indexterm id="IG31371888298"><primary>pmlogger tool</primary><secondary>configuration +</secondary></indexterm><indexterm id="ITch07-17"><primary>pmlc tool</primary> +<secondary>description</secondary></indexterm>You may tailor <command>pmlogger</command> +dynamically with the <command>pmlc</command> command (if it is configured to allow access +to this functionality). Normally, +the <command>pmlogger</command> configuration is read at startup. If you choose +to modify the <filename>config</filename> file to change the parameters under +which <command>pmlogger</command> operates, you must stop and restart the +program for your changes to have effect. Alternatively, you may change parameters +whenever required by using the <command>pmlc</command> interface.</para> +<para>To run the <command>pmlc</command> tool, enter:</para> +<literallayout class="monospaced"><userinput>pmlc</userinput></literallayout> +<para>By default, <command>pmlc</command> acts on the primary instance of <command>pmlogger</command> +on the current host. See the <command>pmlc(1)</command> +man page for a description of command line options. When it is +invoked, <command>pmlc</command> presents you with a prompt:</para> +<literallayout class="monospaced">pmlc> </literallayout> +<para>You may obtain a listing of the available commands by entering a question +mark (?) and pressing <keycap>Enter</keycap>. You see output similar to that +in <xref linkend="Z984165791sdc"/>:</para> +<example id="Z984165791sdc"> +<title>Listing Available Commands +</title> +<literallayout class="monospaced"> show loggers [@<host>] display <pid>s of running pmloggers + connect _logger_id [@<host>] connect to designated pmlogger + status information about connected pmlogger + query metric-list show logging state of metrics + new volume start a new log volume + flush flush the log buffers to disk + log { mandatory | advisory } on <interval> _metric-list + log { mandatory | advisory } off _metric-list + log mandatory maybe _metric-list + timezone local|logger|'<timezone>' change reporting timezone + help print this help message + quit exit from pmlc + _logger_id is primary | <pid> | port <n> + _metric-list is _metric-spec | { _metric-spec ... } + _metric-spec is <metric-name> | <metric-name> [ <instance> ... ]</literallayout> +<para>Here is an example:</para> +<literallayout class="monospaced"><userinput>pmlc</userinput> +pmlc> <userinput>show loggers @babylon</userinput> +The following pmloggers are running on babylon: + primary (1892) +pmlc> <userinput>connect 1892 @babylon</userinput> +pmlc> <userinput>log advisory on 2 secs disk.dev.read</userinput> +pmlc> <userinput>query disk.dev</userinput> +disk.dev.read + adv on nl 5 min [131073 or “disk1”] + adv on nl 5 min [131074 or “disk2”] +pmlc> <userinput>quit</userinput></literallayout> +</example> +<note><para>Any changes to the set of logged metrics made via <command>pmlc</command> +are not saved, and are lost the next time <command>pmlogger</command> +is started with the same configuration file. Permanent changes are made by +modifying the <command>pmlogger</command> configuration file(s).</para> +</note> +<para>Refer to the <command>pmlc(1)</command> and <command>pmlogger(1)</command> +man pages for complete details.</para> +</section> +</section> +<section id="LE80113-PARENT"> + +<title>Archive Logging Troubleshooting</title> +<para><indexterm id="ITch07-19"><primary>troubleshooting</primary><secondary> +archive logging</secondary></indexterm><indexterm id="IG31371888299"><primary>archive logs</primary> +<secondary>troubleshooting</secondary></indexterm><indexterm id="IG31371888300"><primary>pmlogger +tool</primary><secondary>troubleshooting</secondary></indexterm>The following +issues concern the creation and use of logs using <command>pmlogger</command>. +</para> +<section id="id5209540"> + +<title><command>pmlogger</command> Cannot Write Log</title> +<variablelist> +<varlistentry> +<term>Symptom:</term> +<listitem><para>The <command>pmlogger</command> utility does not start, and +you see this message:</para> +<literallayout class="monospaced"><literal>__pmLogNewFile: “foo.index” already exists, not over-written</literal></literallayout> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para>Archive logs are considered sufficiently precious that +<command>pmlogger</command> does not empty or overwrite an existing set of archive +log files. The log named <filename>foo</filename> actually consists of the +physical file <filename>foo.index</filename>, <filename>foo.meta</filename>, +and at least one file <filename>foo.N</filename>, where <filename>N</filename> +is in the range 0, 1, 2, 3, and so on.</para> +<para>A message similar to the one above is produced when a new <command>pmlogger</command> +instance encounters one of these files already in existence.</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para>Move the existing archive aside, or if you are sure, +remove all of the parts of the archive log. +For example, use the following command:<literallayout class="monospaced"><userinput>rm -f foo.*</userinput></literallayout></para> +<para>Then rerun <command>pmlogger</command>.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5209654"> + +<title>Cannot Find Log</title> +<variablelist> +<varlistentry> +<term>Symptom:</term> +<listitem><para><indexterm id="ITch07-23"><primary>pmdumplog tool</primary> +<secondary>troubleshooting</secondary></indexterm>The <literal>pmdumplog</literal> +utility, or any tool that can read an archive log, displays this message: +</para> +<literallayout class="monospaced"><literal>Cannot open archive mylog: No such file or directory</literal></literallayout> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para>An archive consists of at least three physical files. If the +base name for the archive is <filename>mylog</filename>, then the archive +actually consists of the physical files <filename>mylog.index</filename>, +<filename>mylog.meta</filename>, and at least one file <filename>mylog.N</filename>, +where <filename>N</filename> is in the range 0, 1, 2, 3, and so on.</para> +<para>The above message is produced if one or more of the files is missing. +</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para>Use this command to check which files the utility is trying +to open:</para> +<para><literallayout class="monospaced"><userinput>ls mylog.*</userinput></literallayout></para> +<para>Turn on the internal debug flag <literal>DBG_TRACE_LOG</literal> (<literal>-D</literal> 128) to see which files are being inspected by the <literal>__pmOpenLog</literal> routine as shown in the following example:<literallayout class="monospaced"><userinput>pmdumplog -D 128 -l mylog</userinput></literallayout></para> +<para>Locate the missing files and move them all to the same directory, or +remove all of the files that are part of the archive, and recreate the archive +log.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5209840"> + +<title>Primary <command>pmlogger</command> Cannot Start</title> +<variablelist> +<varlistentry> +<term>Symptom:</term> +<listitem><para>The primary <command>pmlogger</command> cannot be started. +A message like the following appears:</para> +<literallayout class="monospaced"><literal>pmlogger: there is already a primary pmlogger running</literal></literallayout> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para>There is either a primary <command>pmlogger</command> already +running, or the previous primary <command>pmlogger</command> was terminated +unexpectedly before it could perform its cleanup operations.</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para><indexterm id="IG31371888301"><primary>show command</primary></indexterm><indexterm id="IG31371888302"> +<primary>pmlc tool</primary><secondary>show command</secondary></indexterm><indexterm id="IG31371888303"> +<primary>SIGINT signal</primary></indexterm><indexterm id="IG31371888304"><primary>kill command +</primary></indexterm>If there is already a primary <command>pmlogger</command> +running and you wish to replace it with a new <command>pmlogger</command>, +use the <literal>show</literal> command in <command>pmlc</command> to determine +the process ID of the primary <command>pmlogger</command>. The process ID +of the primary <command>pmlogger</command> appears in parentheses after the +word “primary.” Send a <literal>SIGINT</literal> signal to the +process to shut it down (use either the <command>kill</command> command if +the platform supports it, or the <command>pmsignal</command> command). If the +process does not exist, proceed to the manual cleanup described in the paragraph +below. If the process did exist, it should now be possible to start the new <command>pmlogger</command>.</para> +<para>If <command>pmlc</command>'s <command>show</command> command displays +a process ID for a process that does not exist, a <command>pmlogger</command> +process was terminated before it could clean up. If it was the primary <command>pmlogger</command>, +the corresponding control files must be removed before +one can start a new primary <command>pmlogger</command>. It is a good idea +to clean up any spurious control files even if they are not for the primary <command>pmlogger</command>.</para> +<para><indexterm id="IG31371888305"><primary>${PCP_TMP_DIR}/pmlogger files</primary></indexterm>The +control files are kept in <filename>${PCP_TMP_DIR}/pmlogger</filename>. A control +file with the process ID of the <command>pmlogger</command> as its name is +created when the <command>pmlogger</command> is started. In addition, the +primary <command>pmlogger</command> creates a symbolic link named <literal>primary</literal> to its control file.</para> +<para>For the primary <command>pmlogger</command>, remove both the symbolic +link and the file (corresponding to its process ID) to which the link points. +For other <command>pmlogger</command>s, remove just the process ID file. Do +not remove any other files in the directory. If the control file for an active +<command>pmlogger</command> is removed, <command>pmlc</command> is not able to contact +it.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5210097"> + +<title>Identifying an Active <command>pmlogger</command> Process</title> +<variablelist> +<varlistentry> +<term>Symptom:</term> +<listitem><para><indexterm id="IG31371888306"><primary>active pmlogger process</primary></indexterm>You +have a PCP archive log that is demonstrably growing, but do not know the identify +of the associated <command>pmlogger</command> process.</para> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para>The PID is not obvious from the log, or the archive name may +not be obvious from the output of the <command>ps</command> command.</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para>If the archive basename is <filename>foo</filename>, run the +following commands:</para> +<literallayout class="monospaced"><userinput>pmdumplog -l foo</userinput> +<literal>Log Label (Log Format Version 1)</literal> +Performance metrics from host gonzo + commencing Wed Aug 7 00:10:09.214 1996 + ending Wed Aug 7 16:10:09.155 1996 + +<userinput>pminfo -a foo -f pmcd.pmlogger</userinput>  +pmcd.pmlogger.host + inst [10728 or "10728"] value "gonzo" +pmcd.pmlogger.port + inst [10728 or "10728"] value 4331 +pmcd.pmlogger.archive + inst [10728 or "10728"] value "<replaceable>/usr/var/adm/pcplog/gonzo/foo</replaceable>"</literallayout> +<para>All of the information describing the creator of the archive is revealed +and, in particular, the instance identifier for the PMCD metrics (<literal>10728</literal> in the example above) is the PID of the <command>pmlogger</command> instance, which may be used to control the process via <command>pmlc</command>.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5210268"> + +<title>Illegal Label Record</title> +<variablelist> +<varlistentry> +<term>Symptom:</term> +<listitem><para><indexterm id="IG31371888307"><primary>illegal label record</primary></indexterm>PCP +tools report:</para> +<literallayout class="monospaced">Illegal label record at start of PCP archive log file.</literallayout> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para>The label record at the start of each of the physical archive +log files has become either corrupted or one is out of sync with the others. +</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para> +If you believe the log may have been corrupted, this can be verified using <command>pmlogcheck</command>. +If corruption is limited to just the label record at the start, the <command>pmloglabel</command> +can be used to force the labels back in sync with each other, with known-good values that you supply.</para> +<para>Refer to the <command>pmlogcheck(1)</command> and <command>pmloglabel(1)</command> man pages.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5210389"> + +<title>Empty Archive Log Files or <command>pmlogger</command> Exits Immediately +</title> +<variablelist id="Z930351569sdc"> +<varlistentry> +<term>Symptom:</term> +<listitem><para>Archive log files are zero size, requested metrics are not +being logged, or <command>pmlogger</command> exits immediately with no error +messages.</para> +</listitem></varlistentry> +<varlistentry> +<term>Cause:</term> +<listitem><para>Either <command>pmlogger</command> encountered errors in the +configuration file, has not flushed its output buffers yet, or some (or all) +metrics specified in the <command>pmlogger</command> configuration file have +had their state changed to advisory <literal>off</literal> or mandatory <literal>off</literal> via <command>pmlc</command>. It is also possible that the logging +interval specified in the <command>pmlogger</command> configuration file for +some or all of the metrics is longer than the period of time you have been +waiting since <command>pmlogger</command> started.</para> +</listitem></varlistentry> +<varlistentry> +<term>Resolution:</term> +<listitem><para>If <command>pmlogger</command> exits immediately with no error +messages, check the <filename>pmlogger.log</filename> file in the directory +<command>pmlogger</command> was started in for any error messages. +If <command>pmlogger</command> has not yet flushed its buffers, enter one of +the following commands (depending on platform support): +<literallayout class="monospaced">killall -SIGUSR1 pmlogger +${PCP_BINADM_DIR}/pmsignal -a -s USR1 pmlogger</literallayout></para> +<para>Otherwise, use the <literal>status</literal> command for <command>pmlc</command> +to interrogate the internal <command>pmlogger</command> state of +specific metrics.</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +</chapter> + + + +<chapter id="LE83321-PARENT"> + +<title>Performance Co-Pilot Deployment Strategies</title> +<para><indexterm id="IG31371888308"><primary>deployment strategies</primary></indexterm>Performance +Co-Pilot (PCP) is a coordinated suite of tools and utilities allowing +you to monitor performance and make automated judgments and initiate actions +based on those judgments. PCP is designed to be fully configurable for +custom implementation and deployed to meet specific needs in a variety +of operational environments.</para> +<para>Because each enterprise and site is different and PCP represents +a new way of managing performance information, some discussion of deployment +strategies is useful.</para> +<para><indexterm id="IG31371888309"><primary>PMCD</primary><secondary>monitoring utilities +</secondary></indexterm><indexterm id="IG31371888310"><primary>PMDA</primary><secondary> +monitoring utilities</secondary></indexterm>The most common use of performance +monitoring utilities is a scenario where the PCP tools are executed on +a workstation (the PCP monitoring system), while the interesting performance +data is collected on remote systems (PCP collector systems) by a number +of processes, specifically the Performance Metrics Collection Daemon (PMCD) +and the associated Performance Metrics Domain Agents (PMDAs). These processes +can execute on both the monitoring system and one or more collector systems, +or only on collector systems. However, collector systems are the real +objects of performance investigations.</para> +<para>The material in this chapter covers the following areas:</para> +<itemizedlist> +<listitem><para><xref linkend="LE85282-PARENT"/>, presents the spectrum +of deployment architectures at the highest level.</para> +</listitem> +<listitem><para><xref linkend="LE69500-PARENT"/>, describes alternative +deployments for PMCD and the PMDAs.</para> +</listitem> +<listitem><para><xref linkend="LE56598-PARENT"/>, covers alternative deployments +for the <command>pmlogger</command> tool.</para> +</listitem> +<listitem><para><xref linkend="LE62310-PARENT"/>, presents the options +that are available for deploying the <command>pmie</command> tool.</para> +</listitem></itemizedlist> +<para>The options shown in this chapter are merely suggestions. They are +not comprehensive, and are intended to demonstrate some possible ways +of deploying the PCP tools for specific network topologies and purposes. +You are encouraged to use them as the basis for planning your own deployment, +consistent with your needs.</para> +<section id="LE85282-PARENT"> + +<title>Basic Deployment</title> +<para>In the simplest PCP deployment, one system is configured as both +a collector and a monitor, as shown in <xref linkend="id5210776"/>. +Because some of the PCP monitor tools make extensive use of visualization, this +suggests the monitor system should be configured with a graphical display.</para> +<figure id="id5210776"><title>PCP Deployment for a Single System</title><mediaobject><imageobject><imagedata fileref="figures/local-deploy.svg"/></imageobject><textobject><phrase>PCP Deployment for a Single System</phrase></textobject></mediaobject></figure> +<para>However, most PCP deployments involve at least two systems. For +example, the setup shown in <xref linkend="id5210808"/> would be representative +of many common scenarios.</para> +<figure id="id5210808"><title>Basic PCP Deployment for Two Systems</title><mediaobject><imageobject><imagedata fileref="figures/remote-deploy.svg"/></imageobject><textobject><phrase>Basic PCP Deployment for Two Systems</phrase></textobject></mediaobject></figure> +<para>But the most common site configuration would include a mixture of +systems configured as PCP collectors, as PCP monitors, and as both PCP +monitors and collectors, as shown in <xref linkend="id5210866"/>.</para> +<para>With one or more PCP collector systems and one or more PCP monitor +systems, there are a number of decisions that need to be made regarding +the deployment of PCP services across multiple hosts. For example, in <xref linkend="id5210866"/> +there are several ways in which both the inference engine (<command>pmie</command>) +and the PCP archive logger (<command>pmlogger</command>) could be deployed. +These options are discussed in the following sections of this chapter.</para> +<figure id="id5210866"><title>General PCP Deployment for Multiple Systems +</title><mediaobject><imageobject><imagedata fileref="figures/multi-deploy.svg"/></imageobject><textobject><phrase>General PCP Deployment for Multiple Systems +</phrase></textobject></mediaobject></figure> +</section> +<section id="LE69500-PARENT"> + +<title>PCP Collector Deployment</title> +<para><indexterm id="ITch08-0"><primary>PCP</primary><secondary>collector +deployment</secondary></indexterm>Each PCP collector system must have +an active <literal>pmcd</literal> and, typically, a number of PMDAs installed. +</para> +<section id="id5210938"> + +<title>Principal Server Deployment</title> +<para>The first hosts selected as PCP collector systems are likely to +provide some class of service deemed to be critical to the information +processing activities of the enterprise. These hosts include: +</para> +<itemizedlist> +<listitem><para>Database servers</para> +</listitem> +<listitem><para>Web servers for an Internet or Intranet presence</para> +</listitem> +<listitem><para>NFS or other central storage server</para> +</listitem> +<listitem><para>A video server</para> +</listitem> +<listitem><para>A supercomputer</para> +</listitem> +<listitem><para>An infrastructure service provider, for example, print, +DNS, LDAP, gateway, firewall, router, or mail services</para> +</listitem> +<listitem><para>Any system running a mission-critical application</para> +</listitem></itemizedlist> +<para>Your objective may be to improve quality of service on a system +functioning as a server for many clients. You wish to identify and repair +critical performance bottlenecks and deficiencies in order to maintain +maximum performance for clients of the server.</para> +<para>For some of these services, the PCP base product or the PCP add-on +packages provide the necessary collector components. Others would require +customized PMDA development, as described in the companion +<citetitle>Performance Co-Pilot Programmer's Guide</citetitle>.</para> +</section> +<section id="id5211030"> + +<title>Quality of Service Measurement</title> +<para><indexterm id="IG31371888311"><primary>service management</primary></indexterm>Applications +and services with a client-server architecture need to monitor performance +at both the server side and the client side.</para> +<para>The arrangement in <xref linkend="id5211102"/> illustrates one +way of measuring quality of service for client-server applications.</para> +<figure id="id5211102"><title>PCP Deployment to Measure Client-Server Quality +of Service</title><mediaobject><imageobject><imagedata fileref="figures/qos-deploy.svg"/></imageobject><textobject><phrase>PCP Deployment to Measure Client-Server Quality +of Service</phrase></textobject></mediaobject></figure> +<para>The configuration of the PCP collector components on the Application +Server System is standard. The new facility is the deployment of some +PCP collector components on the Application Client System; this uses a +customized PMDA and a generalization of the ICMP “ping” tool +as follows:</para> +<itemizedlist> +<listitem><para>The <literal>Client App</literal> is specially developed +to periodically make typical requests of the <literal>App Server</literal>, +and to measure the response time for these requests (this is an application-specific “ping”). +</para> +</listitem> +<listitem><para>The PMDA on the Application Client System captures the +response time measurements from the <literal>Client App</literal> and +exports these into the PCP framework.</para> +</listitem></itemizedlist> +<para>At the PCP monitor system, the performance of the system running +the <literal>App Server</literal> and the end-user quality of service +measurements from the system where the <literal>Client App</literal> is +running can be monitored concurrently.</para> +<para>PCP contains a number of examples of this architecture, including +the <literal>shping</literal> PMDA for IP-based services (including +HTTP), and the <literal>dbping</literal> PMDA for database servers.</para> +<para>The source code for each of these PMDAs is readily available; +users and administrators are encouraged to adapt these agents to the +needs of the local application environment.</para> +<para>It is possible to exploit this arrangement even further, with these +methods:</para> +<itemizedlist> +<listitem><para>Creating new instances of the <literal>Client App</literal> +and PMDA to measure service quality for your own mission-critical services. +</para> +</listitem> +<listitem><para>Deploying the <literal>Client App</literal> and associated +PCP collector components in a number of strategic hosts allows the quality +of service over the enterprise's network to be monitored. For example, +service can be monitored on the Application Server System, on the same +LAN segment as the Application Server System, on the other side of a firewall +system, or out in the WAN.</para> +</listitem></itemizedlist> +</section> +</section> +<section id="LE56598-PARENT"> + +<title>PCP Archive Logger Deployment</title> +<para><indexterm id="ITch08-3"><primary>PCP</primary><secondary>archive +logger deployment</secondary></indexterm>PCP archive logs are created +by the <command>pmlogger</command> utility, as discussed in <xref linkend="LE93354-PARENT"/>. +They provide a critical capability to perform retrospective performance +analysis, for example, to detect performance regressions, for problem +analysis, or to support capacity planning. The following sections discuss +the options and trade-offs for <command>pmlogger</command> deployment. +</para> +<section id="id5211332"> + +<title>Deployment Options</title> +<para>The issue is relatively simple and reduces to “On which host(s) +should <command>pmlogger</command> be running?” The options are +these:</para> +<itemizedlist> +<listitem><para>Run <command>pmlogger</command> on each PCP collector +system to capture local performance data.</para> +</listitem> +<listitem><para>Run <command>pmlogger</command> on some of the PCP monitor +systems to capture performance data from remote PCP collector systems. +</para> +</listitem> +<listitem><para>As an extension of the previous option, designate one +system to act as the PCP archive site to run all <command>pmlogger</command> +instances. This arrangement is shown in <xref linkend="id5211413"/>. +</para> +<figure id="id5211413"><title>Designated PCP Archive Site</title><mediaobject><imageobject><imagedata fileref="figures/designated-logger.svg"/></imageobject><textobject><phrase>Designated PCP Archive Site</phrase></textobject></mediaobject></figure> +</listitem></itemizedlist> +</section> +<section id="id5211434"> + +<title>Resource Demands for the Deployment Options</title> +<para>The <command>pmlogger</command> process is very lightweight in terms +of computational demand; most of the (very small) CPU cost is associated with +extracting performance metrics at the PCP collector system (PMCD and the +PMDAs), which are independent of the host on which <command>pmlogger</command> +is running.</para> +<para>A local <command>pmlogger</command> consumes disk bandwidth and +disk space on the PCP collector system. A remote <command>pmlogger</command> +consumes disk space on the site where it is running and network bandwidth +between that host and the PCP collector host.</para> +<para>The archive logs typically grow at a rate of anywhere between a few +kilobytes (KB) to tens of megabytes (MB) per day, depending on how many +performance metrics are logged and the choice of sampling frequencies. +There are some advantages in minimizing the number of hosts over which the +disk resources for PCP archive logs must be allocated; however, the aggregate +requirement is independent of where the <command>pmlogger</command> processes +are running.</para> +</section> +<section id="id5211489"> + +<title>Operational Management</title> +<para>There is an initial administrative cost associated with configuring +each <command>pmlogger</command> instance, and an ongoing administrative +investment to monitor these configurations, perform regular housekeeping +(such as rotation, compression, and culling of PCP archive log files), +and execute periodic tasks to process the archives (such as nightly performance +regression checking with <command>pmie</command>).</para> +<para>Many of these tasks are handled by the supplied <command>pmlogger</command> +administrative tools and scripts, as described in <xref linkend="LE92914-PARENT"/>. +However, the necessity and importance of these tasks favor a centralized <command> +pmlogger</command> deployment, as shown in <xref linkend="id5211413"/>. +</para> +</section> +<section id="id5211573"> + +<title>Exporting PCP Archive Logs</title> +<para><indexterm id="IG31371888312"><primary>archive logs</primary><secondary>export</secondary> +</indexterm>Collecting PCP archive logs is of little value unless the +logs are processed as part of the ongoing performance monitoring and management +functions. This processing typically involves the use of the tools on +a PCP monitor system, and hence the archive logs may need to be read on +a host different from the one they were created on.</para> +<para>NFS mounting is obviously an option, but the PCP tools support random +access and both forward and backward temporal motion within an archive +log. If an archive is to be subjected to intensive and interactive processing, +it may be more efficient to copy the files of the archive log to the PCP +monitor system first.</para> +<note><para>Each PCP archive log consists of at least three separate files +(see <xref linkend="LE92914-PARENT"/> for details). You must have concurrent +access to all of these files before a PCP tool is able to process an archive +log correctly.</para> +</note> +</section> +</section> +<section id="LE62310-PARENT"> + +<title>PCP Inference Engine Deployment</title> +<para>The <command>pmie</command> utility supports automated reasoning +about system performance, as discussed in <xref linkend="LE21414-PARENT"/>, +and plays a key role in monitoring system performance for both real-time +and retrospective analysis, with the performance data being retrieved +respectively from a PCP collector system and a PCP archive log.</para> +<para>The following sections discuss the options and trade-offs for +<command>pmie</command> deployment.</para> +<section id="id5211669"> + +<title>Deployment Options</title> +<para>The issue is relatively simple and reduces to “On which host(s) +should <command>pmie</command> be running?” You must consider both +real-time and retrospective uses, and the options are as follows:</para> +<itemizedlist> +<listitem><para>For real-time analysis, run <command>pmie</command> on +each PCP collector system to monitor local system performance.</para> +</listitem> +<listitem><para>For real-time analysis, run <command>pmie</command> on +some of the PCP monitor systems to monitor the performance of remote PCP +collector systems.</para> +</listitem> +<listitem><para>For retrospective analysis, run <command>pmie</command> +on the systems where the PCP archive logs reside. The problem then reduces +to <command>pmlogger</command> deployment as discussed in <xref linkend="LE56598-PARENT"/>. +</para> +</listitem> +<listitem><para>As an example of the “distributed management with +centralized control” philosophy, designate some system to act as +the PCP Management Site to run all <command>pmlogger</command> and <command>pmie</command> +instances. This arrangement is shown in <xref linkend="id5211805"/>. +</para> +</listitem></itemizedlist> +<para>One <command>pmie</command> instance is capable of monitoring multiple +PCP collector systems; for example, to evaluate some universal rules that +apply to all hosts. At the same time a single PCP collector system may +be monitored by multiple <command>pmie</command> instances; for example, +for site-specific and universal rule evaluation, or to support both tactical +performance management (operations) and strategic performance management +(capacity planning). Both situations are depicted in <xref linkend="id5211805"/>. +</para> +<figure id="id5211805"><title>PCP Management Site Deployment</title><mediaobject><imageobject><imagedata fileref="figures/designated-manager.svg"/></imageobject><textobject><phrase>PCP Management Site Deployment</phrase></textobject></mediaobject></figure> +</section> +<section id="id5211825"> + +<title>Resource Demands for the Deployment Options</title> +<para>Depending on the complexity of the rule sets, the number of hosts +being monitored, and the evaluation frequency, <command>pmie</command> +may consume CPU cycles significantly above the resources required to simply +fetch the values of the performance metrics. If this becomes significant, +then real-time deployment of <command>pmie</command> away from the PCP +collector systems should be considered in order to avoid the “you're +part of the problem, not the solution” scenario in terms of CPU +utilization on a heavily loaded server.</para> +</section> +<section id="id5211850"> + +<title>Operational Management</title> +<para>An initial administrative cost is associated with configuring each +<command>pmie</command> instance, particularly in the development of the rule sets +that accurately capture and classify “good” versus “bad” +performance in your environment. These rule sets almost always involve +some site-specific knowledge, particularly in respect to the “normal” +levels of activity and resource consumption. The <command>pmieconf</command> +tool (see <xref linkend="Z927039566sdc"/>) may be used to help develop +localized rules based upon parameterized templates covering many common +performance scenarios. In complex environments, customizing these rules +may occur over an extended period and require considerable performance +analysis insight.</para> +<para>One of the functions of <command>pmie</command> provides for continual +detection of adverse performance and the automatic generation of alarms +(visible, audible, e-mail, pager, and so on). Uncontrolled deployment +of this alarm initiating capability throughout the enterprise may cause +havoc.</para> +<para>These considerations favor a centralized <command>pmie</command> +deployment at a small number of PCP monitor sites, or in a PCP Management +Site as shown in <xref linkend="id5211805"/>.</para> +<para>However, it is most likely that knowledgeable users with specific +needs may find a local deployment of <command>pmie</command> most useful +to track some particular class of service difficulty or resource utilization. +In these cases, the alarm propagation is unlikely to be required or is +confined to the system on which <command>pmie</command> is running.</para> +<para>Configuration and management of a number of <command>pmie</command> +instances is made much easier with the scripts and control files described +in <xref linkend="Z927039824sdc"/>.</para> +</section> +</section> +</chapter> + + + +<chapter id="LE62564-PARENT"> + +<title>Customizing and Extending PCP Services</title> +<para><indexterm id="IG31371888313"><primary>customization</primary><secondary>PCP services</secondary> +</indexterm><indexterm id="IG31371888314"><primary>extensibility</primary></indexterm> Performance +Co-Pilot (PCP) has been developed to be fully extensible. The following sections +summarize the various facilities provided to allow you to extend and customize +PCP for your site:</para> +<itemizedlist> +<listitem><para><xref linkend="LE61335-PARENT"/>, describes the procedure for +customizing the summary PMDA to export derived metrics formed by aggregation +of base PCP metrics from one or more collector hosts.</para> +</listitem> +<listitem><para><xref linkend="LE80685-PARENT"/>, describes the various options +available for customizing and extending the basic PCP tools.</para> +</listitem> +<listitem><para><xref linkend="LE50224-PARENT"/>, covers the concepts and tools +provided for updating the PMNS (Performance Metrics Name Space).</para> +</listitem> +<listitem><para><xref linkend="LE10270-PARENT"/>, details where to find further +information to assist in the development of new PMDAs to extend the range +of performance metrics available through the PCP infrastructure.</para> +</listitem> +<listitem><para><xref linkend="LE31248-PARENT"/>, outlines how new tools may +be developed to process performance data from the PCP infrastructure.</para> +</listitem></itemizedlist> +<section id="LE61335-PARENT"> + +<title>PMDA Customization</title> +<para>The generic procedures for installing and activating the optional PMDAs +have been described in <xref linkend="LE43202-PARENT"/>. In some cases, these +procedures prompt the user for information based upon the local system or +network configuration, application deployment, or processing profile to customize +the PMDA and hence the performance metrics it exports.</para> +<para>The summary PMDA is a special case that warrants further discussion. +</para> +<section id="LE43074-PARENT"> + +<title>Customizing the Summary PMDA</title> +<para><indexterm id="ITch09-1"><primary>PMDA</primary><secondary>customizing +</secondary></indexterm>The summary PMDA exports performance metrics derived +from performance metrics made available by other PMDAs. It is described completely +in the <command>pmdasummary(1)</command> man page.</para> +<para>The summary PMDA consists of two processes:</para> +<variablelist> +<varlistentry> +<term><command>pmie</command> process</term> +<listitem><para>Periodically samples the base metrics and compute values for +the derived metrics. This dedicated instance of the PCP <command>pmie</command> +inference engine is launched with special command line arguments by the main +process. See <xref linkend="LE41170-PARENT"/>, for a complete discussion of +the <command>pmie</command> feature set.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>main</literal> process</term> +<listitem><para>Reads and buffers the values computed by the <command>pmie</command> +process and makes them available to the Performance Metrics Collection Daemon +(PMCD).</para> +</listitem></varlistentry> +</variablelist> +<para>All of the metrics exported by the summary PMDA have a singular instance +and the values are instantaneous; the exported value is the correct value +as of the last time the corresponding expression was evaluated by the +<command>pmie</command> process.</para> +<para>The summary PMDA resides in the <literal>${PCP_PMDAS_DIR}/summary</literal> +directory and may be installed with a default configuration by following the +steps described in <xref linkend="LE31599-PARENT"/>.</para> +<para>Alternatively, you may customize the summary PMDA to export your own +derived performance metrics by following the steps in <xref linkend="id5212322"/>: +</para> +<procedure id="id5212322"> +<title>Customizing the Summary PMDA</title> +<step><para>Check that the symbolic constant <literal>SYSSUMMARY</literal> is defined in the <filename>${PCP_VAR_DIR}/pmns/stdpmid</filename> +file. If it is not, perform the postinstall update of this file, as superuser: +<literallayout class="monospaced"><userinput>cd ${PCP_VAR_DIR}/pmns +./Make.stdpmid</userinput></literallayout></para> +</step><step><para><indexterm id="IG31371888315"><primary>PMNS</primary><secondary>names +</secondary></indexterm>Choose Performance Metric Name Space (PMNS) names +for the new metrics. These must begin with <literal>summary</literal> and +follow the rules described in the <command>pmns(5)</command> man +page. For example, you might use <literal>summary.fs.cache_write</literal> +and <literal>summary.fs.cache_hit</literal>.</para> +</step><step><para><indexterm id="IG31371888316"><primary>PMID</primary><secondary>PMNS +names</secondary></indexterm>Edit the <filename>pmns</filename> file in the <literal>${PCP_PMDAS_DIR}/summary</literal> +directory to add the new metric names in +the format described in the <command>pmns(5)</command> man page. +You must choose a unique performance metric identifier (PMID) for each metric. +In the <filename>pmns</filename> file, these appear as <literal>SYSSUMMARY:0:x</literal>. +The value of <replaceable>x</replaceable> is arbitrary in the +range 0 to 1023 and unique in this file. Refer to <xref linkend="LE50224-PARENT"/>, +for a further explanation of the rules governing PMNS updates.</para> +<para>For example:</para> +<literallayout class="monospaced">summary { + cpu + disk + netif + fs /*new*/ +} +summary.fs { + cache_write SYSSUMMARY:0:10 + cache_hit SYSSUMMARY:0:11 +}</literallayout> +</step><step><para>Use the local test PMNS <literal>root</literal> +and validate that the PMNS changes are correct.</para> +<para>For example, enter this command:</para> +<literallayout class="monospaced"><userinput>pminfo -n root -m summary.fs</userinput></literallayout> +<para>You see output similar to the following:</para> +<literallayout class="monospaced">summary.fs.cache_write PMID: 27.0.10 +summary.fs.cache_hit PMID: 27.0.11</literallayout> +</step><step><para>Edit the <filename>${PCP_PMDAS_DIR}/summary/expr.pmie</filename> +file to add new <command>pmie</command> expressions. If the name +to the left of the assignment operator (=) is one of the PMNS names, then +the <command>pmie</command> expression to the right will be evaluated and +returned by the summary PMDA. The expression must return a numeric value. +Additional description of the <command>pmie</command> expression syntax may +be found in <xref linkend="LE90227-PARENT"/>.</para> +<para>For example, consider this expression:</para> +<literallayout class="monospaced">// filesystem buffer cache hit percentages +prefix = "kernel.all.io"; // macro, not exported +summary.fs.cache_write = + 100 - 100 * $prefix.bwrite / $prefix.lwrite; +summary.fs.cache_hit = + 100 - 100 * $prefix.bread / $prefix.lread;</literallayout> +</step><step><para>Run <command>pmie</command> in debug mode to verify +that the expressions are being evaluated correctly, and the values make sense. +</para> +<para>For example, enter this command:</para> +<literallayout class="monospaced"><userinput>pmie -t 2sec -v expr.pmie</userinput></literallayout> +<para>You see output similar to the following:</para> +<literallayout class="monospaced">summary.fs.cache_write: ? +summary.fs.cache_hit: ? +summary.fs.cache_write: 45.83 +summary.fs.cache_hit: 83.2 +summary.fs.cache_write: 39.22 +summary.fs.cache_hit: 84.51</literallayout> +</step><step><para>Install the new PMDA.</para> +<para>From the <literal>${PCP_PMDAS_DIR}/summary</literal> directory, +use this command:</para> +<literallayout class="monospaced"><userinput>./Install</userinput></literallayout> +<para>You see the following output:</para> +<literallayout class="monospaced">You need to choose an appropriate configuration for installation of +the “summary” Performance Metrics Domain Agent (PMDA). + +collector collect performance statistics on this system +monitor allow this system to monitor local and/or remote systems +both collector and monitor configuration for this system + +Please enter c(ollector) or m(onitor) or b(oth) [b] <userinput>both</userinput> +Interval between summary expression evaluation (seconds)? [10] <userinput>10</userinput> +Updating the Performance Metrics Name Space... +Installing pmchart view(s) ... +Terminate PMDA if already installed ... +Installing files .. +Updating the PMCD control file, and notifying PMCD ... +Wait 15 seconds for the agent to initialize ... +Check summary metrics have appeared ... 8 metrics and 8 values</literallayout> +</step> +<step><para>Check the metrics.</para> +<para>For example, enter this command:</para> +<literallayout class="monospaced"><userinput>pmval -t 5sec -s 8 summary.fs.cache_write</userinput></literallayout> +<para>You see a response similar to the following:</para> +<literallayout class="monospaced">metric: summary.fs.cache_write +host: localhost +semantics: instantaneous value +units: none +samples: 8 +interval: 5.00 sec +63.60132158590308 +62.71878646441073 +62.71878646441073 +58.73968492123031 +58.73968492123031 +65.33822758259046 +65.33822758259046 +72.6099706744868</literallayout> +<para>Note that the values are being sampled here by <literal>pmval</literal> +every 5 seconds, but <command>pmie</command> is passing only new values to +the summary PMDA every 10 seconds. Both rates could be changed to suit the +dynamics of your new metrics.</para> +</step><step><para>You may now create <command>pmchart</command> views, +<command>pmie</command> rules, and <command>pmlogger</command> +configurations to monitor and archive your new performance metrics.</para> +</step> +</procedure> +</section> +</section> +<section id="LE80685-PARENT"> + +<title>PCP Tool Customization</title> +<para><indexterm id="ITch09-2"><primary>PCP</primary><secondary>tool customization +</secondary></indexterm><indexterm id="IG31371888317"><primary>tool customization</primary></indexterm>Performance +Co-Pilot (PCP) has been designed and implemented with a philosophy that embraces +the notion of toolkits and encourages extensibility.</para> +<para>In most cases, the PCP tools provide orthogonal services, based on external +configuration files. It is the creation of new and modified configuration +files that enables PCP users to customize tools quickly and meet the needs +of the local environment, in many cases allowing personal preferences to be +established for individual users on the same PCP monitor system.</para> +<para>The material in this section is intended to act as a checklist of pointers +to detailed documentation found elsewhere in this guide, in the man pages, +and in the files that are made available as part of the PCP installation. +</para> +<section id="id5212794"> + +<title>Archive Logging Customization</title> +<para><indexterm id="IG31371888318"><primary>archive logs</primary><secondary>customization</secondary> +</indexterm><indexterm id="IG31371888319"><primary>customization</primary><secondary>archive +logs</secondary></indexterm>The PCP archive logger is presented in <xref linkend="LE93354-PARENT"/>, +and documented in the <command>pmlogger(1)</command> man page. +</para> +<para>The following global files and directories influence the behavior of +<command>pmlogger</command>:</para> +<variablelist condition="sgi_termlength:nextline" id="Z930367453sdc"> +<varlistentry> +<term><filename>${PCP_SYSCONF_DIR}/pmlogger</filename> </term> +<listitem><para>Enable/disable state for the primary logger facility using +this command:<literallayout class="monospaced"><userinput><literal>chkconfig pmlogger on</literal></userinput></literallayout></para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_SYSCONF_DIR}/pmlogger/config.default</filename> </term> +<listitem><para>The default <command>pmlogger</command> configuration file +that is used for the primary logger when this facility is enabled.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_VAR_DIR}/config/pmlogconf/tools</filename> </term> +<listitem><para>Every PCP tool with a fixed group of performance metrics contributes +a <command>pmlogconf</command> configuration file that includes each of the +performance metrics used in the tool, for example, <filename>${PCP_VAR_DIR}/config/pmlogconf/pmstat</filename> +for <literal>pmstat</literal>.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_PMLOGGERCONTROL_PATH}</filename> </term> +<listitem><para>Defines which PCP collector hosts require +<command>pmlogger</command> to be launched on the local host, where the configuration file +comes from, where the archive log files should be created, and <command>pmlogger</command> +startup options.</para> +<para>This <literal>control</literal> file supports the starting and stopping of multiple +<command>pmlogger</command> instances that monitor local or remote hosts.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>/etc/cron.d/pcp-pmlogger</filename> or <filename>${PCP_VAR_DIR}/config/pmlogger/crontab</filename> </term> +<listitem><para>Default <literal>crontab</literal> entries that may be merged +with the <literal>crontab</literal> entries for the <literal>pcp</literal> user +to schedule the periodic execution of the archive log management scripts, for +example, <literal>pmlogger_daily</literal>.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_LOG_DIR}/pmlogger/somehost</filename> </term> +<listitem><para>The default behavior of the archive log management scripts +create archive log files for the host <replaceable>somehost</replaceable> +in this directory.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_LOG_DIR}/pmlogger/somehost/Latest</filename> </term> +<listitem><para>A PCP archive folio for the most recent archive for the host <replaceable>somehost</replaceable>. +This folio is created and maintained by the <literal>cron</literal>-driven periodic archive log management scripts, for example, <literal>pmlogger_check</literal>. Archive folios may be processed with the <literal>pmafm</literal> tool.</para> +</listitem></varlistentry> +</variablelist> +</section> +<section id="id5213167"> + +<title>Inference Engine Customization</title> +<para><indexterm id="IG31371888320"><primary>inference engine</primary></indexterm><indexterm id="IG31371888321"> +<primary>customization</primary><secondary>inference engine</secondary></indexterm>The +PCP inference engine is presented in <xref linkend="LE21414-PARENT"/>, and +documented in the <command>pmie(1)</command> man page.</para> +<para>The following global files and directories influence the behavior of <command>pmie</command>:</para> +<variablelist condition="sgi_termlength:nextline" id="Z930367570sdc"> +<varlistentry> +<term><filename>${PCP_SYSCONF_DIR}/pmie</filename></term> +<listitem><para>Controls the pmie daemon facility. Enable using this command:<literallayout class="monospaced">chkconfig pmie on</literallayout></para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_SYSCONF_DIR}/pmie/config.default</filename></term> +<listitem><para>The <command>pmie</command> configuration file that is used +for monitoring the local host when the <command>pmie</command> daemon facility +is enabled in the default configuration. This file is created using <command>pmieconf</command> +the first time the daemon facility is activated.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_PMIECONTROL_PATH}</filename></term> +<listitem><para>Defines which PCP collector hosts require a daemon <command>pmie</command> +to be monitoring from the local host, where the configuration files comes from, +where the <command>pmie</command> log file should be created, +and <command>pmie</command> startup options.</para> +<para>This <literal>control</literal> file supports the starting and stopping of multiple +<command>pmie</command> instances that are each monitoring one or more hosts.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_VAR_DIR}/config/pmieconf/*/*</filename></term> +<listitem><para>Each <command>pmieconf</command> rule definition can be found +below one of these subdirectories.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>/etc/cron.d/pcp-pmie</filename> or <filename>${PCP_VAR_DIR}/config/pmie/crontab</filename> </term> +<listitem><para>Default <literal>crontab</literal> entries that may be merged +with the <literal>crontab</literal> entries for the <literal>pcp</literal> user +to schedule the periodic execution of the <command>pmie_check</command> and +<command>pmie_daily</command> scripts, for verifying that <command>pmie</command> +instances are running and logs rotated.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_LOG_DIR}/pmie/somehost</filename></term> +<listitem><para>The default behavior of the <filename>${PCP_RC_DIR}/pmie</filename> +startup scripts create <command>pmie</command> log files for the host +<replaceable>somehost</replaceable> in this directory.</para> +</listitem></varlistentry> +<varlistentry> +<term><command>pmie_check</command> and <command>pmie_daily</command></term> +<listitem><para>These commands are similar to the <command>pmlogger</command> +support scripts, <command>pmlogger_check</command> and <command>pmlogger_daily</command>.</para> +</listitem></varlistentry> +<varlistentry> +<term><filename>${PCP_TMP_DIR}/pmie</filename></term> +<listitem><para>The statistics that <command>pmie</command> gathers are maintained +in binary data structure files. These files can be found in the +<filename>${PCP_TMP_DIR}/pmie</filename> directory.</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>pmcd.pmie</literal> metrics</term> +<listitem><para>The PMCD PMDA exports information about executing <command>pmie</command> +processes and their progress in terms of rule evaluations and action execution +rates.</para> +<para>If <command>pmie</command> is running on a system with a PCP +collector deployment, the <command>pmcd</command> PMDA exports these metrics +via the <filename>pmcd.pmie</filename> group of metrics.</para> +</listitem></varlistentry> +</variablelist> +</section> +</section> +<section id="LE50224-PARENT"> + +<title>PMNS Management</title> +<para><indexterm id="IG31371888322"><primary>PMNS</primary><secondary>management</secondary> +</indexterm>This section describes the syntax, semantics, and processing framework +for the external specification of a Performance Metrics Name Space (PMNS) +as it might be loaded by the PMAPI routine <command>pmLoadNameSpace</command>; +see the <command>pmLoadNameSpace(3)</command> man page. This is usually done only +by <command>pmcd</command>, except in rare circumstances such as <xref linkend="LE43074-PARENT"/>. +</para> +<para>The PMNS specification is a simple text source file that can be edited +easily. For reasons of efficiency, a binary format is also supported; the +utility <literal>pmnscomp</literal> translates the ASCII source format into +binary format; see the <command>pmnscomp(1)</command> man page. +</para> +<section id="id5213650"> + +<title>PMNS Processing Framework</title> +<para>The PMNS specification is initially passed through <command>pmcpp(1)</command>. +This means the following facilities may be used in the specification:</para> +<itemizedlist> +<listitem><para>C-style comments</para> +</listitem> +<listitem><para><literal>#include</literal> directives</para> +</listitem> +<listitem><para><literal>#define</literal> directives and macro substitution +</para> +</listitem> +<listitem><para>Conditional processing with <literal>#ifdef</literal>, +<literal>#ifndef</literal>, <literal>#endif</literal>, and <literal>#undef</literal></para> +</listitem></itemizedlist> +<para>When <command>pmcpp(1)</command> is executed, the standard include directories +are the current directory and <literal>${PCP_VAR_DIR}/pmns</literal>, where some +standard macros and default specifications may be found.</para> +</section> +<section id="id5213751"> + +<title>PMNS Syntax</title> +<para><indexterm id="ITch09-4"><primary>PMNS</primary><secondary>syntax</secondary> +</indexterm><indexterm id="IG31371888323"><primary>syntax</primary></indexterm>Every PMNS is +tree structured. The paths to the leaf nodes are the performance metric names. +The general syntax for a non-leaf node in PMNS is as follows:</para> +<literallayout class="monospaced">pathname { + name [pmid] + ... +}</literallayout> +<para>Here <literal>pathname</literal> is the full pathname from the root +of the PMNS to this non-leaf node, with each component in the path separated +by a period. The root node for the PMNS has the special name <literal>root</literal>, but the prefix string <literal>root.</literal> must be omitted +from all other <literal>pathnames</literal>.</para> +<para>For example, refer to the PMNS shown in <xref linkend="id5213846"/>. +The correct pathname for the rightmost non-leaf node is <literal>cpu.utilization</literal>, not <literal>root.cpu.utilization</literal>.</para> +<figure id="id5213846"><title>Small Performance Metrics Name Space (PMNS)</title><mediaobject><imageobject><imagedata fileref="figures/pmns-small2.svg"/></imageobject><textobject><phrase>Small Performance Metrics Name Space (PMNS)</phrase></textobject></mediaobject></figure> +<para>Each component in the pathname must begin with an alphabetic character +and be followed by zero or more alphanumeric characters or the underscore +(_) character. For alphabetic characters in a component, uppercase and lowercase +are significant.</para> +<para>Non-leaf nodes in the PMNS may be defined in any order desired. The +descendent nodes are defined by the set of <literal>names</literal>, relative +to the pathname of their parent non-leaf node. For descendent nodes, leaf +nodes have a <literal>pmid</literal> specification, but non-leaf nodes do +not.</para> +<para>The syntax for the <literal>pmid</literal> specification was chosen +to help manage the allocation of Performance Metric IDs (PMIDs) across disjoint +and autonomous domains of administration and implementation. Each <literal>pmid</literal> consists of three integers separated by colons, for example, <literal>14:27:11</literal>. This is intended to mirror the implementation hierarchy +of performance metrics. The first integer identifies the domain in which the +performance metric lies. Within a domain, related metrics are often grouped +into clusters. The second integer identifies the cluster, and the third integer, +the metric within the cluster.</para> +<para>The PMNS specification for <xref linkend="id5213846"/> is shown in <xref linkend="Z928447759sdc"/>:</para> +<example id="Z928447759sdc"> +<title>PMNS Specification</title> +<literallayout class="monospaced">/* +* PMNS Specification +*/ +#define KERNEL 1 +root { + network + cpu +} +#define NETWORK 26 +network { + interrupts KERNEL:NETWORK:1 + packets +} +network.packets { + in KERNEL:NETWORK:35 + out KERNEL:NETWORK:36 +} +#define CPU 10 +cpu { + syscalls KERNEL:CPU:10 + utilization +} +#define USER 20 +#define SYSTEM 21 +#define IDLE 22 +cpu.utilization { + user KERNEL:CPU:USER + sys KERNEL:CPU:SYSTEM + idle KERNEL:CPU:IDLE +}</literallayout> +</example> +<para>For complete documentation of the PMNS and associated utilities, see +the <command>pmns(5)</command>, <command>pmnsadd(1)</command>, +<command>pmnsdel(1)</command> and <command>pmnsmerge(1)</command> man pages. +</para> +</section> +</section> +<section id="LE10270-PARENT"> + +<title>PMDA Development</title> +<para><indexterm id="ITch09-5"><primary>PMDA</primary><secondary>development +</secondary></indexterm>Performance Co-Pilot (PCP) is designed to be extensible +at the collector site.</para> +<para>Application developers are encouraged to create new PMDAs to export +performance metrics from the applications and service layers that are particularly +relevant to a specific site, application suite, or processing environment. +</para> +<para>These PMDAs use the routines of the <literal>libpcp_pmda</literal> library, +which is discussed in detail in the <citetitle>Performance Co-Pilot Programmer's Guide</citetitle>.</para> +</section> +<section id="LE31248-PARENT"> + +<title>PCP Tool Development</title> +<para><indexterm id="ITch09-6"><primary>PCP</primary><secondary>tool development +</secondary></indexterm><indexterm id="IG31371888324"><primary>tool development</primary></indexterm>Performance +Co-Pilot (PCP) is designed to be extensible at the monitor site.</para> +<para>Application developers are encouraged to create new PCP client applications +to monitor or display performance metrics in a manner that is particularly +relevant to a specific site, application suite, or processing environment. +</para> +<para>Client applications use the routines of the PMAPI (performance metrics +application programming interface) described in the <citetitle>Performance Co-Pilot Programmer's Guide</citetitle>. +At the time of writing, native PMAPI interfaces are available for the C, C++ and +Python languages.</para> +</section> +</chapter> + + +<appendix id="LE65325-PARENT"> + +<title>Acronyms</title> +<para><indexterm id="ITchA-0"><primary>acronyms</primary></indexterm><indexterm id="ITchA-1"><primary>glossary</primary></indexterm><xref linkend="id5214266"/> +provides a list of the acronyms used in the Performance Co-Pilot +(PCP) documentation, help cards, man pages, and user interface.</para> +<table id="id5214266" frame="topbot"> + +<title>Performance Co-Pilot Acronyms and Their Meanings +</title> +<tgroup cols="2" colsep="0" rowsep="0"> +<colspec colwidth="120*"/> +<colspec colwidth="276*"/> +<thead> +<row rowsep="1" valign="top"><entry align="left" valign="bottom"><para>Acronym</para></entry> +<entry align="left" valign="bottom"><para>Meaning</para></entry></row> +</thead> +<tbody> +<row valign="top"> +<entry align="left" valign="top"><para>API</para></entry> +<entry align="left" valign="top"><para>Application Programming Interface +</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para>DBMS</para></entry> +<entry align="left" valign="top"><para>Database Management System</para></entry> +</row> +<row valign="top"> +<entry align="left" valign="top"><para>DNS</para></entry> +<entry align="left" valign="top"><para>Domain Name Service</para></entry> +</row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31371888325"><primary>DSO</primary> +</indexterm> DSO</para></entry> +<entry align="left" valign="top"><para>Dynamic Shared Object</para></entry> +</row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31371888326"><primary>I/O</primary> +</indexterm> I/O</para></entry> +<entry align="left" valign="top"><para>Input/Output</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="IG31371888327"><primary>IPC</primary> +</indexterm> IPC</para></entry> +<entry align="left" valign="top"><para>Interprocess Communication</para></entry> +</row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-4"><primary> +PCP</primary><secondary>acronym</secondary></indexterm> PCP</para></entry> +<entry align="left" valign="top"><para>Performance Co-Pilot</para></entry> +</row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-5"><primary> +PDU</primary></indexterm> PDU</para></entry> +<entry align="left" valign="top"><para>Protocol data unit</para></entry> +</row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-6"><primary> +PMAPI</primary><secondary>acronym</secondary></indexterm> PMAPI</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Application +Programming Interface</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-7"><primary> +PMCD</primary><secondary>acronym</secondary></indexterm> PMCD</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Collection +Daemon</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-9"><primary> +PMD</primary></indexterm> PMD</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Domain</para></entry> +</row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-10"><primary> +PMDA</primary><secondary>acronym</secondary></indexterm> PMDA</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Domain Agent +</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-11"><primary> +PMID</primary><secondary>acronym</secondary></indexterm> PMID</para></entry> +<entry align="left" valign="top"><para>Performance Metric Identifier</para></entry> +</row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-12"><primary> +PMNS</primary><secondary>acronym</secondary></indexterm> PMNS</para></entry> +<entry align="left" valign="top"><para>Performance Metrics Name Space +</para></entry></row> +<row valign="top"> +<entry align="left" valign="top"><para><indexterm id="ITchA-13"><primary> +TCP/IP</primary><secondary>acronym</secondary></indexterm> TCP/IP</para></entry> +<entry align="left" valign="top"><para>Transmission Control Protocol/Internet +Protocol</para></entry></row></tbody></tgroup></table> +</appendix> +<index id="sgi-index"> + +<indexentry> + <primaryie>*_inst operator <link linkend="IG31371888221">Arithmetic Aggregation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>*_sample operator <link linkend="IG31371888222">Arithmetic Aggregation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>2D tools <link linkend="IG31371888171">Monitoring System Performance</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>64-bit IEEE format <link linkend="IG3137188876">Descriptions for Performance Metrics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmGetConfig function <link linkend="IG31371888139">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>acronyms <link linkend="ITchA-0">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>active pmlogger process <link linkend="IG31371888306">Identifying an Active <command>pmlogger</command> Process</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>adaptation <link linkend="IG3137188815">Dynamic Adaptation to Change</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>application programs <link linkend="ITch01-114">Application and Agent Development</link> <link linkend="IG3137188869">Sources of Performance Metrics and Their Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>archive logs</primaryie> + <secondaryie>administration <link linkend="IG31371888290">Archive Log Administration</link></secondaryie> + <secondaryie>analysis <link linkend="IG3137188816">Logging and Retrospective Analysis</link></secondaryie> + <secondaryie>capacity planning <link linkend="IG31371888249">Using Archive Logs for Capacity Planning</link></secondaryie> + <secondaryie>collection time <link linkend="ITch01-135">Current Metric Context</link></secondaryie> + <secondaryie>contents <link linkend="IG31371888268">PCP Archive Contents</link></secondaryie> + <secondaryie>creation <link linkend="IG3137188836">Collecting, Transporting, and Archiving Performance Information +</link></secondaryie> + <secondaryie>customization <link linkend="IG3137188819">Automated Operational Support</link> <link linkend="IG31371888318">Archive Logging Customization</link></secondaryie> + <secondaryie>export <link linkend="IG31371888312">Exporting PCP Archive Logs</link></secondaryie> + <secondaryie>fetching metrics <link linkend="ITch03-5">Fetching Metrics from an Archive Log</link></secondaryie> + <secondaryie>file management <link linkend="IG31371888260">Archive Log File Management</link></secondaryie> + <secondaryie>folios <link linkend="IG31371888291">PCP Archive Folios</link></secondaryie> + <secondaryie>physical filenames <link linkend="ITch03-9">Fetching Metrics from an Archive Log</link></secondaryie> + <secondaryie>PMAPI <link linkend="IG31371888245">Archive Logs and the PMAPI</link></secondaryie> + <secondaryie>retrospective analysis <link linkend="IG31371888247">Retrospective Analysis Using Archive Logs</link></secondaryie> + <secondaryie>troubleshooting <link linkend="IG31371888299">Archive Logging Troubleshooting</link></secondaryie> + <secondaryie>usage <link linkend="IG31371888239">Archive Logging</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>arithmetic aggregation <link linkend="IG31371888215">Arithmetic Aggregation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>arithmetic expressions <link linkend="IG31371888199"><command>pmie</command> Arithmetic Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>audience <link linkend="IG313718884">Empowering the PCP User</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>audits <link linkend="IG3137188820">Automated Operational Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>automated operational support <link linkend="IG3137188817">Automated Operational Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>avg_host operator <link linkend="IG31371888216">Arithmetic Aggregation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>basename conventions <link linkend="IG31371888261">Basename Conventions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Boolean expressions <link linkend="IG31371888203">Boolean Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>capacity planning <link linkend="IG31371888250">Using Archive Logs for Capacity Planning</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>caveats <link linkend="IG31371888229">Caveats and Notes on <command>pmie</command></link></primaryie> +</indexentry> + +<indexentry> + <primaryie>centralized archive logging <link linkend="IG3137188818">Automated Operational Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>coverage <link linkend="IG3137188824">Metric Coverage</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>chkhelp tool <link linkend="ITch01-115">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>client-server architecture <link linkend="IG3137188813">PCP Distributed Operation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>collection time <link linkend="ITch01-134">Current Metric Context</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>collector hosts <link linkend="ITch01-143">Distributed Collection</link> <link linkend="ITch01-156">Collector and Monitor Roles</link> <link linkend="ITch02-33">PMDA Installation on a PCP Collector Host</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>comments <link linkend="IG31371888190">Comments </link></primaryie> +</indexentry> + +<indexentry> + <primaryie>common directories <link linkend="IG31371888119">Common Directories and File Locations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>component software <link linkend="IG3137188826">Overview of Component Software</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>conceptual foundations <link linkend="ITch01-129">Conceptual Foundations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>configuring PCP <link linkend="ITch02-1">Installing and Configuring Performance Co-Pilot +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>conventions <link linkend="ITch03-1">Common Conventions and Arguments</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>cookbook <link linkend="IG31371888270">Cookbook for Archive Logging</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>count_host operator <link linkend="IG31371888218">Arithmetic Aggregation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>cron scripts <link linkend="IG31371888242">Introduction to Archive Logging</link> <link linkend="ITch07-6">Administering PCP Archive Logs Using <command>cron</command> Scripts +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>customization</primaryie> + <secondaryie>archive logs <link linkend="IG31371888319">Archive Logging Customization</link></secondaryie> + <secondaryie>inference engine <link linkend="IG31371888321">Inference Engine Customization</link></secondaryie> + <secondaryie>PCP services <link linkend="IG31371888313">Customizing and Extending PCP Services</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>data collection tools <link linkend="IG3137188834">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>dbpmda tool <link linkend="ITch01-117">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>debugging tools <link linkend="ITch01-90">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>deployment strategies <link linkend="IG31371888308">Performance Co-Pilot Deployment Strategies</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>diagnostic tools <link linkend="IG3137188851">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>DISPLAY variable <link linkend="IG31371888207"><command>pmie</command> Rule Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>distributed collection <link linkend="ITch01-142">Distributed Collection</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>domains <link linkend="IG313718885">Unification of Performance Metric Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>DSO <link linkend="IG31371888325">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>duration <link linkend="IG31371888131">Performance Monitor Reporting Frequency and +Duration</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>dynamic adaptation <link linkend="IG3137188814">Dynamic Adaptation to Change</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>environ man page <link linkend="IG31371888135">Timezone Options</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>environment variables <link linkend="IG31371888136">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>error detection <link linkend="IG31371888233"><command>pmie</command> Error Detection</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_PMLOGGERCONTROL_PATH} file <link linkend="IG31371888296">Primary Logger</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_DIR}/etc/pcp.conf file <link linkend="IG31371888122">Common Directories and File Locations</link> <link linkend="IG31371888137">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_DIR}/etc/pcp.env file <link linkend="IG31371888121">Common Directories and File Locations</link> <link linkend="IG31371888138">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_RC_DIR}/pmcd file <link linkend="IG31371888127">Common Directories and File Locations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>evaluation frequency <link linkend="IG31371888193">Setting Evaluation Frequency</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>extensibility <link linkend="IG3137188821">PCP Extensibility</link> <link linkend="IG31371888314">Customizing and Extending PCP Services</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>external equipment <link linkend="IG3137188871">Sources of Performance Metrics and Their Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>fetching metrics <link linkend="ITch03-3">Fetching Metrics from Another Host</link> <link linkend="ITch03-6">Fetching Metrics from an Archive Log</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>file locations <link linkend="IG31371888120">Common Directories and File Locations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>firewalls <link linkend="IG31371888153">Running PCP Tools through a Firewall</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>flush command <link linkend="IG31371888253">Coordination between <command>pmlogger</command> and PCP tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>folios <link linkend="ITch07-9">PCP Archive Folios</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>functional domains <link linkend="ITch01-138">Sources of Performance Metrics and Their Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>glossary <link linkend="ITchA-1">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>illegal label record <link linkend="IG31371888307">Illegal Label Record</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>inference engine <link linkend="IG31371888320">Inference Engine Customization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>infrastructure support tools <link linkend="ITch01-76">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>installing PCP <link linkend="ITch02-0">Installing and Configuring Performance Co-Pilot +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>intrinsic operators <link linkend="IG31371888213"><command>pmie</command> Intrinsic Operators</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>I/O <link linkend="IG31371888326">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>IPC <link linkend="IG31371888327">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>kill command <link linkend="IG31371888304">Primary <command>pmlogger</command> Cannot Start</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>layered software services <link linkend="IG3137188868">Sources of Performance Metrics and Their Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>lexical elements <link linkend="IG31371888189">Lexical Elements</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>libpcp_mmv library <link linkend="IG3137188886">Product Extensibility</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>libpcp_pmda library <link linkend="IG3137188885">Product Extensibility</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>log volumes <link linkend="IG31371888262">Log Volumes</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>logging</primaryie> + <seeie>archive logs</seeie> +</indexentry> + +<indexentry> + <primaryie>logical constants <link linkend="IG31371888201">Logical Constants</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>logical expressions <link linkend="IG31371888200"><command>pmie</command> Logical Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>macros <link linkend="IG31371888191">Macros</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>man command</primaryie> + <secondaryie>usage <link linkend="IG31371888168">Monitoring System Performance</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>max_host operator <link linkend="IG31371888220">Arithmetic Aggregation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>metadata <link linkend="ITch01-150">Descriptions for Performance Metrics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>metric domains <link linkend="IG313718886">Unification of Performance Metric Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>metric wraparound <link linkend="IG31371888231">Performance Metrics Wraparound</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>min_host operator <link linkend="IG31371888219">Arithmetic Aggregation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>mkaf tool <link linkend="ITch01-48">Collecting, Transporting, and Archiving Performance Information +</link> <link linkend="IG31371888243">Introduction to Archive Logging</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>monitor configuration <link linkend="ITch02-5">Product Structure</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>monitor hosts <link linkend="IG3137188881">Collector and Monitor Roles</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>monitoring system performance <link linkend="IG31371888166">Monitoring System Performance</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>naming scheme <link linkend="IG3137188810">Uniform Naming and Access to Performance Metrics +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>netstat command <link linkend="IG31371888111">PMCD Does Not Start</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>network routers and bridges <link linkend="IG3137188870">Sources of Performance Metrics and Their Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>network transportation tools <link linkend="IG3137188835">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>newhelp tool <link linkend="ITch01-119">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Mail servers <link linkend="IG3137188867">Sources of Performance Metrics and Their Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>objectives <link linkend="IG313718882">Objectives</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>operational support tools <link linkend="IG3137188848">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>operators <link linkend="IG31371888205">Quantification Operators</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>overview <link linkend="ITch01-0">Introduction to Performance Co-Pilot</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmatop tool</primaryie> + <secondaryie>brief description <link linkend="IG3137188800">Performance Monitoring and Visualization</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmcd.options file <link linkend="ITch02-27">The <filename>pmcd.options</filename> File</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCP</primaryie> + <secondaryie>acronym <link linkend="ITchA-4">Acronyms</link></secondaryie> + <secondaryie>archive logger deployment <link linkend="ITch08-3">PCP Archive Logger Deployment</link></secondaryie> + <secondaryie>collector deployment <link linkend="ITch08-0">PCP Collector Deployment</link></secondaryie> + <secondaryie>configuring and installing <link linkend="ITch02-3">Installing and Configuring Performance Co-Pilot +</link></secondaryie> + <secondaryie>conventions <link linkend="ITch03-0">Common Conventions and Arguments</link></secondaryie> + <secondaryie>distributed operation <link linkend="ITch01-2">PCP Distributed Operation</link></secondaryie> + <secondaryie>environment variables <link linkend="ITch03-14">PCP Environment Variables</link></secondaryie> + <secondaryie>extensibility <link linkend="IG3137188822">PCP Extensibility</link> <link linkend="ITch01-160">Product Extensibility</link></secondaryie> + <secondaryie>features <link linkend="IG313718880">Introduction to Performance Co-Pilot</link></secondaryie> + <secondaryie>log file option <link linkend="ITch03-8">Fetching Metrics from an Archive Log</link></secondaryie> + <secondaryie>naming conventions <link linkend="ITch03-2">Common Conventions and Arguments</link></secondaryie> + <secondaryie>pmie capabilities <link linkend="IG31371888177">Introduction to <command>pmie</command></link></secondaryie> + <secondaryie>pmie tool <link linkend="ITch06-7"><command>pmie</command> use of PCP services</link></secondaryie> + <secondaryie>tool customization <link linkend="ITch09-2">PCP Tool Customization</link></secondaryie> + <secondaryie>tool development <link linkend="ITch09-6">PCP Tool Development</link></secondaryie> + <secondaryie>tool summaries <link linkend="IG3137188827">Performance Monitoring and Visualization</link> <link linkend="IG3137188833">Collecting, Transporting, and Archiving Performance Information +</link> <link linkend="IG3137188847">Operational and Infrastructure Support</link> <link linkend="IG3137188860">Application and Agent Development</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pcp tool <link linkend="IG3137188850">Operational and Infrastructure Support</link> <link linkend="IG3137188859">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCP Tutorials and Case Studies</primaryie> + <secondaryie>pminfo command <link linkend="IG31371888176">The <command>pminfo</command> Command</link></secondaryie> + <secondaryie>pmval command <link linkend="IG31371888173">The <command>pmval</command> Command</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>PCP_COUNTER_WRAP variable <link linkend="ITch03-15">PCP Environment Variables</link> <link linkend="IG31371888165">Performance Metric Wraparound</link> <link linkend="IG31371888230">Performance Metrics Wraparound</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCP_STDERR variable <link linkend="ITch03-18">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PCPIntro command <link linkend="IG31371888112">PMCD Does Not Start</link> <link linkend="IG31371888132">Performance Monitor Reporting Frequency and +Duration</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PDU <link linkend="ITch02-28">The <filename>pmcd.options</filename> File</link> <link linkend="ITchA-5">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>Performance Co-Pilot</primaryie> + <seeie>PCP</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metric Identifier</primaryie> + <seeie>PMID</seeie> +</indexentry> + +<indexentry> + <primaryie>performance metric wraparound <link linkend="ITch03-32">Performance Metric Wraparound</link> <link linkend="ITch06-21">Performance Metrics Wraparound</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>performance metrics</primaryie> + <secondaryie>concept <link linkend="IG3137188863">Performance Metrics</link></secondaryie> + <secondaryie>descriptions <link linkend="ITch01-149">Descriptions for Performance Metrics</link></secondaryie> + <secondaryie>methods <link linkend="ITch01-139">Sources of Performance Metrics and Their Domains</link></secondaryie> + <secondaryie>missing and incomplete values <link linkend="ITch02-39">Missing and Incomplete Values for Performance Metrics +</link></secondaryie> + <secondaryie>PMNS <link linkend="ITch01-148">Performance Metrics Name Space</link></secondaryie> + <secondaryie>retrospective sources <link linkend="ITch01-159">Retrospective Sources of Performance Metrics</link></secondaryie> + <secondaryie>sources <link linkend="ITch01-137">Sources of Performance Metrics and Their Domains</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Application Programming Interface</primaryie> + <seeie>PMAPI</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Collection Daemon</primaryie> + <seeie>PMCD</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Domain</primaryie> + <seeie>PMD</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Domain Agent</primaryie> + <seeie>PMDA</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Inference Engine</primaryie> + <seeie>pmie tool</seeie> +</indexentry> + +<indexentry> + <primaryie>Performance Metrics Name Space</primaryie> + <seeie>PMNS</seeie> +</indexentry> + +<indexentry> + <primaryie>performance monitoring <link linkend="IG3137188828">Performance Monitoring and Visualization</link> <link linkend="IG31371888167">Monitoring System Performance</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>performance visualization tools <link linkend="ITch07-4">Using Archive Logs with Performance Tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PM_INDOM_NULL <link linkend="ITch06-8"><command>pmie</command> and the Performance Metrics +Collection System</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmafm tool</primaryie> + <secondaryie>archive folios <link linkend="IG31371888244">Introduction to Archive Logging</link></secondaryie> + <secondaryie>brief description <link linkend="ITch01-50">Collecting, Transporting, and Archiving Performance Information +</link></secondaryie> + <secondaryie>interactive commands <link linkend="IG31371888295">PCP Archive Folios</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>PMAPI</primaryie> + <secondaryie>acronym <link linkend="ITchA-6">Acronyms</link></secondaryie> + <secondaryie>archive logs <link linkend="IG31371888246">Archive Logs and the PMAPI</link></secondaryie> + <secondaryie>brief description <link linkend="IG3137188861">Application and Agent Development</link></secondaryie> + <secondaryie>naming metrics <link linkend="ITch01-130">Performance Metrics</link></secondaryie> + <secondaryie>pmie capabilities <link linkend="IG31371888178">Introduction to <command>pmie</command></link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>PMCD</primaryie> + <secondaryie>acronym <link linkend="ITchA-7">Acronyms</link></secondaryie> + <secondaryie>brief description <link linkend="ITch01-52">Collecting, Transporting, and Archiving Performance Information +</link></secondaryie> + <secondaryie>collector host <link linkend="IG31371888196"><command>pmie</command> Metric Expressions</link></secondaryie> + <secondaryie>configuration files <link linkend="ITch02-26">PMCD Options and Configuration Files</link></secondaryie> + <secondaryie>diagnostics and error messages <link linkend="ITch02-23">PMCD Diagnostics and Error Messages</link></secondaryie> + <secondaryie>distributed collection <link linkend="IG3137188874">Distributed Collection</link> <link linkend="IG3137188875">Distributed Collection</link></secondaryie> + <secondaryie>maintenance <link linkend="ITch02-20">Performance Metrics Collection Daemon (PMCD)</link></secondaryie> + <secondaryie>monitoring utilities <link linkend="IG31371888309">Performance Co-Pilot Deployment Strategies</link></secondaryie> + <secondaryie>not starting <link linkend="IG31371888109">PMCD Does Not Start</link></secondaryie> + <secondaryie>PMCD_CONNECT_TIMEOUT variable <link linkend="IG31371888143">PCP Environment Variables</link></secondaryie> + <secondaryie>PMCD_PORT variable <link linkend="IG31371888144">PCP Environment Variables</link></secondaryie> + <secondaryie>PMCD_RECONNECT_TIMEOUT variable <link linkend="IG31371888146">PCP Environment Variables</link></secondaryie> + <secondaryie>PMCD_REQUEST_TIMEOUT variable <link linkend="IG31371888147">PCP Environment Variables</link></secondaryie> + <secondaryie>remote connection <link linkend="IG31371888101">Cannot Connect to Remote PMCD</link></secondaryie> + <secondaryie>starting and stopping <link linkend="IG3137188891">Starting and Stopping the PMCD</link></secondaryie> + <secondaryie>TCP/IP firewall <link linkend="IG31371888157">Running PCP Tools through a Firewall</link></secondaryie> + <secondaryie>${PCP_PMCDCONF_PATH} file <link linkend="IG31371888124">Common Directories and File Locations</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmcd tool</primaryie> + <seeie>PMCD</seeie> +</indexentry> + +<indexentry> + <primaryie>PMCD_CONNECT_TIMEOUT variable <link linkend="IG31371888106">Cannot Connect to Remote PMCD</link> <link linkend="ITch03-22">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMCD_PORT variable <link linkend="IG31371888160">Running PCP Tools through a Firewall</link> <link linkend="IG31371888113">PMCD Does Not Start</link> <link linkend="ITch03-23">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMCD_RECONNECT_TIMEOUT variable <link linkend="ITch03-24">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMCD_REQUEST_TIMEOUT variable <link linkend="ITch03-25">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmcd_wait tool <link linkend="IG3137188839">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmcd.conf file <link linkend="ITch02-29">The <filename>pmcd.conf</filename> File</link> <link linkend="ITch02-30">Controlling Access to PMCD with <filename>pmcd.conf</filename></link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmchart tool</primaryie> + <secondaryie>brief description <link linkend="IG3137188800nat">Performance Monitoring and Visualization</link></secondaryie> + <secondaryie>fetching metrics <link linkend="IG31371888115">Fetching Metrics from Another Host</link></secondaryie> + <secondaryie>man example <link linkend="Z1033415772tls">Monitoring System Performance</link></secondaryie> + <secondaryie>record mode <link linkend="IG31371888292">PCP Archive Folios</link></secondaryie> + <secondaryie>remote PMCD <link linkend="IG31371888102">Cannot Connect to Remote PMCD</link></secondaryie> + <secondaryie>short-term executions <link linkend="IG31371888265">Directory Organization for Archive Log Files</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmclient tool <link linkend="ITch01-121">Application and Agent Development</link> <link linkend="ITch01-123">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmcollectl tool</primaryie> + <secondaryie>brief description <link linkend="IG3137188801">Performance Monitoring and Visualization</link></secondaryie> + <secondaryie>record mode <link linkend="IG31371888293">PCP Archive Folios</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmconfirm command</primaryie> + <secondaryie>error messages <link linkend="IG31371888141">PCP Environment Variables</link></secondaryie> + <secondaryie>visible alarm <link linkend="IG31371888180">Introduction to <command>pmie</command></link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>PMD <link linkend="IG3137188893">PMDA Installation on a PCP Collector Host</link> <link linkend="ITchA-9">Acronyms</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMDA</primaryie> + <secondaryie>acronym <link linkend="ITchA-10">Acronyms</link></secondaryie> + <secondaryie>collectors <link linkend="IG3137188880">Collector and Monitor Roles</link></secondaryie> + <secondaryie>customizing <link linkend="ITch09-1">Customizing the Summary PMDA</link></secondaryie> + <secondaryie>development <link linkend="ITch09-5">PMDA Development</link></secondaryie> + <secondaryie>installation <link linkend="ITch02-32">PMDA Installation on a PCP Collector Host</link></secondaryie> + <secondaryie>instance names <link linkend="IG31371888197"><command>pmie</command> Metric Expressions</link></secondaryie> + <secondaryie>libraries <link linkend="IG3137188823">PCP Extensibility</link></secondaryie> + <secondaryie>managing optional agents <link linkend="ITch02-31">Managing Optional PMDAs</link></secondaryie> + <secondaryie>monitoring utilities <link linkend="IG31371888310">Performance Co-Pilot Deployment Strategies</link></secondaryie> + <secondaryie>removal <link linkend="ITch02-35">PMDA Removal on a PCP Collector Host</link></secondaryie> + <secondaryie>unification <link linkend="IG313718887">Unification of Performance Metric Domains</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaapache tool <link linkend="IG3137188803">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdacisco tool <link linkend="ITch01-54">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaelasticsearch tool <link linkend="IG3137188714">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdagfs2 tool <link linkend="IG3137188804">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdagluster tool <link linkend="IG3137188712">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdainfiniband tool <link linkend="IG3137188805">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdakvm tool <link linkend="IG3137188806">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdalustrecomm tool <link linkend="IG3137188807">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdamailq tool <link linkend="ITch01-58">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdamemcache tool <link linkend="IG3137188808">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdammv tool <link linkend="IG3137188841">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdamysql tool <link linkend="IG3137188809">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdanamed tool <link linkend="IG3137188701">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdanginx tool <link linkend="IG3137188702">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdapostfix tool <link linkend="IG3137188703">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdapostgresql tool <link linkend="IG3137188704">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaproc tool <link linkend="IG3137188705">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdarsyslog tool <link linkend="IG3137188706">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdasamba tool <link linkend="IG3137188707">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdasendmail tool <link linkend="IG3137188842">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdasnmp tool <link linkend="IG3137188708">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdasummary tool <link linkend="ITch01-62">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdasystemd tool <link linkend="IG3137188709">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdavmware tool <link linkend="IG3137188710">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaweblog tool <link linkend="IG3137188843">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdaxfs tool <link linkend="IG3137188711">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdbg facility <link linkend="ITch01-89">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmdumplog tool</primaryie> + <secondaryie>archive log contents <link linkend="IG31371888269">PCP Archive Contents</link></secondaryie> + <secondaryie>brief description <link linkend="ITch01-66">Collecting, Transporting, and Archiving Performance Information +</link></secondaryie> + <secondaryie>troubleshooting <link linkend="ITch07-23">Cannot Find Log</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmdumptext tool</primaryie> + <secondaryie>brief description <link linkend="ITch01-22">Performance Monitoring and Visualization</link></secondaryie> + <secondaryie>description <link linkend="IG31371888172">The <command>pmdumptext</command> Command</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmerr tool <link linkend="ITch01-91">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmgenmap tool <link linkend="ITch01-125">Application and Agent Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmhostname tool <link linkend="IG3137188852">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMID</primaryie> + <secondaryie>acronym <link linkend="ITchA-11">Acronyms</link></secondaryie> + <secondaryie>description <link linkend="IG3137188872">Sources of Performance Metrics and Their Domains</link> <link linkend="ITch01-146">Performance Metrics Name Space</link></secondaryie> + <secondaryie>PMNS names <link linkend="IG31371888316">Customizing the Summary PMDA</link></secondaryie> + <secondaryie>printing <link linkend="IG31371888174">The <command>pminfo</command> Command</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmie tool</primaryie> + <secondaryie>%-token <link linkend="IG31371888211"><command>pmie</command> Rule Expressions</link></secondaryie> + <secondaryie>arithmetic aggregation <link linkend="IG31371888214">Arithmetic Aggregation</link></secondaryie> + <secondaryie>arithmetic expressions <link linkend="ITch06-15"><command>pmie</command> Arithmetic Expressions</link></secondaryie> + <secondaryie>automated reasoning <link linkend="ITch06-4">Introduction to <command>pmie</command></link></secondaryie> + <secondaryie>basic examples <link linkend="IG31371888186">Basic <command>pmie</command> Usage</link></secondaryie> + <secondaryie>brief description <link linkend="ITch01-32">Performance Monitoring and Visualization</link> <link linkend="IG3137188853">Operational and Infrastructure Support</link></secondaryie> + <secondaryie>customization <link linkend="IG31371888184">Introduction to <command>pmie</command></link></secondaryie> + <secondaryie>developing rules <link linkend="ITch06-20">Developing and Debugging <command>pmie</command> +Rules</link></secondaryie> + <secondaryie>error detection <link linkend="ITch06-24"><command>pmie</command> Error Detection</link></secondaryie> + <secondaryie>examples <link linkend="ITch06-9">Simple <command>pmie</command> Usage</link> <link linkend="ITch06-10">Complex <command>pmie</command> Examples</link></secondaryie> + <secondaryie>fetching metrics <link linkend="IG31371888116">Fetching Metrics from Another Host</link></secondaryie> + <secondaryie>global files and directories <link linkend="IG31371888238">Global Files and Directories</link></secondaryie> + <secondaryie>instance names <link linkend="ITch06-23"><command>pmie</command> Instance Names</link></secondaryie> + <secondaryie>intrinsic operators <link linkend="ITch06-17"><command>pmie</command> Intrinsic Operators</link></secondaryie> + <secondaryie>language <link linkend="IG31371888179">Introduction to <command>pmie</command></link> <link linkend="IG31371888188">Specification Language for <command>pmie</command></link></secondaryie> + <secondaryie>logical expressions <link linkend="ITch06-16"><command>pmie</command> Logical Expressions</link></secondaryie> + <secondaryie>metric expressions <link linkend="ITch06-13"><command>pmie</command> Metric Expressions</link></secondaryie> + <secondaryie>performance metrics inference engine <link linkend="ITch06-0">Performance Metrics Inference Engine</link></secondaryie> + <secondaryie>pmieconf rules <link linkend="IG3137188830">Performance Monitoring and Visualization</link> <link linkend="IG31371888234">Creating <command>pmie</command> Rules with <command> +pmieconf</command></link></secondaryie> + <secondaryie>procedures <link linkend="IG31371888236">Creating <command>pmie</command> Rules with <command> +pmieconf</command></link> <link linkend="IG31371888237">Management of <command>pmie</command> Processes</link></secondaryie> + <secondaryie>rate conversion <link linkend="ITch06-14"><command>pmie</command> Rate Conversion</link></secondaryie> + <secondaryie>rate operator <link linkend="IG31371888223">The <command>rate</command> Operator</link></secondaryie> + <secondaryie>real examples <link linkend="ITch06-18"><command>pmie</command> Examples</link></secondaryie> + <secondaryie>remote PMCD <link linkend="IG31371888103">Cannot Connect to Remote PMCD</link></secondaryie> + <secondaryie>sample intervals <link linkend="ITch06-22"><command>pmie</command> Sample Intervals</link></secondaryie> + <secondaryie>setting evaluation frequency <link linkend="ITch06-12">Setting Evaluation Frequency</link></secondaryie> + <secondaryie>syntax <link linkend="ITch06-11">Basic <command>pmie</command> Syntax</link></secondaryie> + <secondaryie>transitional operators <link linkend="IG31371888225">Transitional Operators</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmevent tool</primaryie> + <secondaryie>brief description <link linkend="IG3137188713">Performance Monitoring and Visualization</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmieconf tool</primaryie> + <secondaryie>brief description <link linkend="IG3137188829">Performance Monitoring and Visualization</link></secondaryie> + <secondaryie>customization <link linkend="IG31371888185">Introduction to <command>pmie</command></link></secondaryie> + <secondaryie>rules <link linkend="IG31371888235">Creating <command>pmie</command> Rules with <command> +pmieconf</command></link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pminfo tool</primaryie> + <secondaryie>brief description <link linkend="ITch01-34">Performance Monitoring and Visualization</link></secondaryie> + <secondaryie>description <link linkend="ITch04-25">The <command>pminfo</command> Command</link></secondaryie> + <secondaryie>displaying the PMNS <link linkend="IG3137188897">Performance Metrics Name Space</link></secondaryie> + <secondaryie>PCP Tutorials and Case Studies <link linkend="IG31371888175">The <command>pminfo</command> Command</link></secondaryie> + <secondaryie>pmie arguments <link linkend="IG31371888187"><command>pmie</command> and the Performance Metrics +Collection System</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmstat tool</primaryie> + <secondaryie>brief description <link linkend="ITch01-37">Performance Monitoring and Visualization</link></secondaryie> + <secondaryie>description <link linkend="ITch04-20">The <command>pmstat</command> Command</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmlc tool</primaryie> + <secondaryie>brief description <link linkend="ITch01-68">Collecting, Transporting, and Archiving Performance Information +</link></secondaryie> + <secondaryie>description <link linkend="ITch07-17">Using <command>pmlc</command></link></secondaryie> + <secondaryie>dynamic adjustment <link linkend="IG31371888240">Introduction to Archive Logging</link></secondaryie> + <secondaryie>flush command <link linkend="IG31371888254">Coordination between <command>pmlogger</command> and PCP tools</link></secondaryie> + <secondaryie>PMLOGGER_PORT variable <link linkend="IG31371888150">PCP Environment Variables</link></secondaryie> + <secondaryie>show command <link linkend="IG31371888302">Primary <command>pmlogger</command> Cannot Start</link></secondaryie> + <secondaryie>SIGHUP signal <link linkend="IG31371888264">Log Volumes</link></secondaryie> + <secondaryie>TCP/IP firewall <link linkend="IG31371888159">Running PCP Tools through a Firewall</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmlock tool <link linkend="ITch01-95">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogcheck tool <link linkend="IG3137188844">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogconf tool <link linkend="IG3137188845">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogextract tool <link linkend="ITch01-72">Collecting, Transporting, and Archiving Performance Information +</link> <link linkend="ITch07-10">Manipulating Archive Logs with <command>pmlogextract</command></link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogger tool <link linkend="IG31371888149">PCP Environment Variables</link> <link linkend="IG31371888208"><command>pmie</command> Rule Expressions</link></primaryie> + <secondaryie>archive logs <link linkend="IG31371888117">Fetching Metrics from an Archive Log</link> <link linkend="ITch07-2">Introduction to Archive Logging</link></secondaryie> + <secondaryie>brief description <link linkend="IG3137188846">Collecting, Transporting, and Archiving Performance Information +</link></secondaryie> + <secondaryie>configuration <link linkend="IG31371888267">Configuration of <command>pmlogger</command></link> <link linkend="IG31371888298">Using <command>pmlc</command></link></secondaryie> + <secondaryie>cookbook tasks <link linkend="IG31371888271">Cookbook for Archive Logging</link></secondaryie> + <secondaryie>current metric context <link linkend="IG3137188865">Current Metric Context</link></secondaryie> + <secondaryie>folios <link linkend="IG31371888294">PCP Archive Folios</link></secondaryie> + <secondaryie>PCP tool coordination <link linkend="IG31371888251">Coordination between <command>pmlogger</command> and PCP tools</link></secondaryie> + <secondaryie>pmlc control <link linkend="IG31371888241">Introduction to Archive Logging</link></secondaryie> + <secondaryie>primary instance <link linkend="ITch07-16">Primary Logger</link></secondaryie> + <secondaryie>remote PMCD <link linkend="IG31371888104">Cannot Connect to Remote PMCD</link></secondaryie> + <secondaryie>TCP/IP firewall <link linkend="IG31371888158">Running PCP Tools through a Firewall</link></secondaryie> + <secondaryie>troubleshooting <link linkend="IG31371888300">Archive Logging Troubleshooting</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogger_check script <link linkend="IG3137188854">Operational and Infrastructure Support</link> <link linkend="ITch07-7">Administering PCP Archive Logs Using <command>cron</command> Scripts +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogger_daily script <link linkend="IG3137188855">Operational and Infrastructure Support</link> <link linkend="IG31371888256">Administering PCP Archive Logs Using <command>cron</command> Scripts +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogger_merge script <link linkend="IG3137188856">Operational and Infrastructure Support</link> <link linkend="IG31371888258">Administering PCP Archive Logs Using <command>cron</command> Scripts +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMLOGGER_PORT variable <link linkend="IG31371888161">Running PCP Tools through a Firewall</link> <link linkend="IG31371888148">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmlogsummary tool <link linkend="IG3137188831">Performance Monitoring and Visualization +</link> <link linkend="ITch07-11">Summarizing Archive Logs with <command>pmlogsummary</command></link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmnewlog tool <link linkend="ITch01-100">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PMNS</primaryie> + <secondaryie>acronym <link linkend="ITchA-12">Acronyms</link></secondaryie> + <secondaryie>brief description <link linkend="IG3137188864">Performance Metrics</link></secondaryie> + <secondaryie>defined names <link linkend="IG3137188811">Uniform Naming and Access to Performance Metrics +</link></secondaryie> + <secondaryie>description <link linkend="ITch01-144">Performance Metrics Name Space</link></secondaryie> + <secondaryie>management <link linkend="IG31371888322">PMNS Management</link></secondaryie> + <secondaryie>metric expressions <link linkend="IG31371888194"><command>pmie</command> Metric Expressions</link></secondaryie> + <secondaryie>names <link linkend="IG31371888315">Customizing the Summary PMDA</link></secondaryie> + <secondaryie>PMNS <link linkend="ITch03-10">Alternate Performance Metric Name Spaces</link></secondaryie> + <secondaryie>syntax <link linkend="ITch09-4">PMNS Syntax</link></secondaryie> + <secondaryie>troubleshooting <link linkend="IG3137188898">Performance Metrics Name Space</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>PMPROXY_PORT variable <link linkend="ITch03-30">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmnsadd tool <link linkend="ITch01-102">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmnsdel tool <link linkend="ITch01-106">Operational and Infrastructure Support</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmprintf tool <link linkend="IG31371888140">PCP Environment Variables</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmprobe tool <link linkend="IG3137188832">Performance Monitoring and Visualization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmrun tool <link linkend="IG31371888114">Common Conventions and Arguments</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmsnap tool</primaryie> + <secondaryie>brief description <link linkend="IG3137188857">Operational and Infrastructure Support</link></secondaryie> + <secondaryie>script usage <link linkend="IG31371888257">Administering PCP Archive Logs Using <command>cron</command> Scripts +</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmproxy tool</primaryie> + <secondaryie>brief description <link linkend="ITch01-38">Performance Monitoring and Visualization</link></secondaryie> + <secondaryie>pmproxy port <link linkend="IG31371888152">PCP Environment Variables</link></secondaryie> + <secondaryie>TCP/IP firewall <link linkend="IG31371888156">Running PCP Tools through a Firewall</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmstore tool</primaryie> + <secondaryie>brief description <link linkend="ITch01-112">Operational and Infrastructure Support</link></secondaryie> + <secondaryie>description <link linkend="ITch04-26">The <command>pmstore</command> Command</link></secondaryie> + <secondaryie>setting metric values <link linkend="IG31371888169">Monitoring System Performance</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmtrace tool <link linkend="ITch01-74">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>pmval tool</primaryie> + <secondaryie>brief description <link linkend="ITch01-42">Performance Monitoring and Visualization</link></secondaryie> + <secondaryie>description <link linkend="ITch04-23">The <command>pmval</command> Command</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>pmwebd tool <link linkend="IG3137188802">Collecting, Transporting, and Archiving Performance Information +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>primary archive <link linkend="IG31371888272">Primary Logger</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>primary logger <link linkend="ITch07-14">Primary Logger</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>protocol data units</primaryie> + <seeie>PDU</seeie> +</indexentry> + +<indexentry> + <primaryie>quantification operators <link linkend="IG31371888204">Quantification Operators</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>rate conversion <link linkend="IG31371888198"><command>pmie</command> Rate Conversion</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>rate operator <link linkend="IG31371888224">The <command>rate</command> Operator</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>relational expressions <link linkend="IG31371888202">Relational Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>reporting frequency <link linkend="IG31371888130">Performance Monitor Reporting Frequency and +Duration</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>retrospective analysis <link linkend="IG31371888248">Retrospective Analysis Using Archive Logs</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>roles</primaryie> + <secondaryie>collector <link linkend="ITch01-155">Collector and Monitor Roles</link> <link linkend="IG3137188888">Product Structure</link></secondaryie> + <secondaryie>monitor <link linkend="IG3137188879">Collector and Monitor Roles</link> <link linkend="IG3137188889">Product Structure</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>rule expressions <link linkend="IG31371888206"><command>pmie</command> Rule Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>sample intervals <link linkend="IG31371888232"><command>pmie</command> Sample Intervals</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>kernel data structures <link linkend="IG3137188866">Sources of Performance Metrics and Their Domains</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>scripts <link linkend="IG3137188858">Operational and Infrastructure Support</link> <link linkend="IG31371888255">Administering PCP Archive Logs Using <command>cron</command> Scripts +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>service management <link linkend="IG31371888311">Quality of Service Measurement</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>set-valued performance metrics <link linkend="IG3137188878">Set-Valued Performance Metrics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>show command <link linkend="IG31371888301">Primary <command>pmlogger</command> Cannot Start</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>SIGHUP signal <link linkend="IG31371888107">PMCD Not Reconfiguring after <literal>SIGHUP</literal></link> <link linkend="IG31371888263">Log Volumes</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>SIGINT signal <link linkend="IG31371888303">Primary <command>pmlogger</command> Cannot Start</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>SIGUSR1 signal <link linkend="IG31371888252">Coordination between <command>pmlogger</command> and PCP tools</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>single-valued performance metrics <link linkend="IG3137188877">Single-Valued Performance Metrics</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>PROXY protocol <link linkend="IG31371888155">Running PCP Tools through a Firewall</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>software <link linkend="IG3137188825">Overview of Component Software</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>subsystems <link linkend="IG3137188887">Product Structure</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>sum_host operator <link linkend="IG31371888217">Arithmetic Aggregation</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>syntax <link linkend="IG31371888323">PMNS Syntax</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>syslog function <link linkend="IG31371888181">Introduction to <command>pmie</command></link> <link linkend="IG31371888209"><command>pmie</command> Rule Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>system log file <link linkend="IG31371888182">Introduction to <command>pmie</command></link> <link linkend="IG31371888212"><command>pmie</command> Rule Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>target usage <link linkend="IG313718883">PCP Target Usage</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>TCP/IP</primaryie> + <secondaryie>acronym <link linkend="ITchA-13">Acronyms</link></secondaryie> + <secondaryie>collector and monitor hosts <link linkend="IG31371888154">Running PCP Tools through a Firewall</link></secondaryie> + <secondaryie>remote PMCD <link linkend="IG31371888105">Cannot Connect to Remote PMCD</link></secondaryie> + <secondaryie>sockets <link linkend="IG31371888145">PCP Environment Variables</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>text-based tools <link linkend="IG31371888170">Monitoring System Performance</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>time dilation <link linkend="ITch03-33">Time Dilation and Time Skew</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>time duration <link linkend="IG31371888129">Time Duration and Control</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>time window options <link linkend="IG31371888133">Time Window Options</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>time-stamped message <link linkend="IG31371888210"><command>pmie</command> Rule Expressions</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>timezone options <link linkend="ITch03-12">Timezone Options</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>tool customization <link linkend="IG31371888317">PCP Tool Customization</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>tool development <link linkend="IG31371888324">PCP Tool Development</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>tool options <link linkend="IG31371888118">General PCP Tool Options</link> <link linkend="ITch06-1">Performance Metrics Inference Engine</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>transient problems <link linkend="IG31371888164">Transient Problems with Performance Metric Values +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>transitional operators <link linkend="IG31371888226">Transitional Operators</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>troubleshooting</primaryie> + <secondaryie>archive logging <link linkend="ITch07-19">Archive Logging Troubleshooting</link></secondaryie> + <secondaryie>general utilities <link linkend="ITch02-42">Cannot Connect to Remote PMCD</link></secondaryie> + <secondaryie>kernel metrics <link linkend="IG3137188899">Kernel Metrics and the PMCD</link></secondaryie> + <secondaryie>PMCD <link linkend="ITch02-38">Troubleshooting</link> <link linkend="IG31371888100">Kernel Metrics and the PMCD</link></secondaryie> +</indexentry> + +<indexentry> + <primaryie>uniform naming <link linkend="IG313718889">Uniform Naming and Access to Performance Metrics +</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>units <link linkend="IG31371888192">Units</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>user interface components <link linkend="Z1033415461tls">Common Conventions and Arguments</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_BINADM_DIR}/pmcd file <link linkend="IG31371888125">Common Directories and File Locations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_LOG_DIR}/NOTICES file <link linkend="IG31371888183">Introduction to <command>pmie</command></link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_LOGDIR}/pmcd/pmcd.log file <link linkend="IG31371888110">PMCD Does Not Start</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_PMCDOPTIONS_PATH} file <link linkend="IG31371888126">Common Directories and File Locations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_PMCDCONF_PATH} file<link linkend="IG3137188896">PMDA Installation on a PCP Collector Host</link> <link linkend="IG31371888108">PMCD Not Reconfiguring after <literal>SIGHUP</literal></link> <link linkend="IG31371888123">Common Directories and File Locations</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_SYSCONF_DIR}/pmlogger/config.default file <link linkend="IG31371888297">Primary Logger</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_PMLOGGERCONTROL_PATH} file <link linkend="IG31371888259">Administering PCP Archive Logs Using <command>cron</command> Scripts +</link> <link linkend="IG31371888266">Directory Organization for Archive Log Files</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_DEMOS_DIR} <link linkend="IG31371888228"><command>pmie</command> Examples</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_VAR_DIR}/pmns/stdpmid file <link linkend="IG3137188895">PMDA Installation on a PCP Collector Host</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>${PCP_TMP_DIR}/pmlogger files <link linkend="IG31371888305">Primary <command>pmlogger</command> Cannot Start</link></primaryie> +</indexentry> + +<indexentry> + <primaryie>window options <link linkend="IG31371888134">Time Window Options</link></primaryie> +</indexentry> + +</index> + +</book> diff --git a/books/PCP_UAG/publican.cfg b/books/PCP_UAG/publican.cfg new file mode 100644 index 0000000..9be140f --- /dev/null +++ b/books/PCP_UAG/publican.cfg @@ -0,0 +1,5 @@ +debug: 1 +xml_lang: en-US +brand: common +condition: common +tmp_dir: . diff --git a/books/README b/books/README new file mode 100644 index 0000000..d700edb --- /dev/null +++ b/books/README @@ -0,0 +1,10 @@ +To render this documentation to PDF or HTML, use one of: + +1) dblatex *.xml +2) xmlto --with-fop pdf *.xml +3) publican build --langs=en-US --formats=pdf + +This is now encoded in the build now as well, publican is +used by default if it is installed, but BOOK_TOOLCHAIN is +available to force an alternative (configure environment +variable, e.g. "BOOK_TOOLCHAIN=xmlto ./configure ..."). |